svelte-palette

KO | EN

gitlite — search

#hacktoberfest #typescript #golang #go #linux #macos #nodejs #java #windows #cli #kubernetes #awesome-list #mcp #ios

(★ 28)

Svelte component to display a customisable color picker

svelte-palette Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<p align="center">
    <img src="assets/svelte-palette.gif" alt="svelte-palette" height="300"/>
</p>
<p align="center">
    Svelte component to display a customisable color picker
</p>

---

[![npm](https://img.shields.io/npm/v/@untemps/svelte-palette?style=for-the-badge)](https://www.npmjs.com/package/@untemps/svelte-palette)
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/untemps/svelte-palette/publish.yml?style=for-the-badge)](https://github.com/untemps/svelte-palette/actions)
[![Codecov](https://img.shields.io/codecov/c/github/untemps/svelte-palette?style=for-the-badge)](https://codecov.io/gh/untemps/svelte-palette)

## Demo

<p align="center">
    :red_circle:&nbsp;<big><a href="https://svelte-palette.vercel.app" target="_blank" rel="noopener">LIVE
    DEMO</a></big>
</p>

## Installation

```bash
yarn add @untemps/svelte-palette
```

> Requires Svelte 5. For Svelte 4 support, use version 4.x.

## Usage

### Basic Usage

```svelte
<script>
    import { Palette } from '@untemps/svelte-palette'

const colors = [
		'#865C54',
		'#8F5447',
		'#A65846',
		'#A9715E',
		'#AD8C72',
    ]

let bgColor = colors[0]
</script>

<main style="--bgColor:{bgColor}">
	<Palette {colors} onselect={({ color }) => (bgColor = color)} />
</main>

## API

| Props                    | Type                                                                                                    | Default | Description                                                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `colors`                 | string[] or Promise<string[]> or object[] or Promise<object[]> or ColorGroup[] or Promise<ColorGroup[]> | []      | Array of colors to be displayed in the palette. Pass an array of `{ name, colors }` objects to display grouped collections. See more about colors in the [Colors Setting](#colors-setting) section        |
| `selectedColor`          | string                                                                                                  | null    | Default selected color. The color must be included in the `colors` prop. Supports `bind:selectedColor`.                                                                                                   |
| `isCompact`              | boolean                                                                                                 | false   | Flag to display the palette in compact mode.                                                                                                                                                              |
| `compactColorIndices`    | number[]                                                                                                | []      | Array of indices to pick from the `colors` array to be displayed in the compacted palette (see [Compact Mode](#compact-mode)).                                                                            |
| `allowDuplicates`        | boolean                                                                                                 | false   | Flag to allow color duplication.                                                                                                                                                                          |
| `deletionMode`           | string                                                                                                  | "none"  | Mode of slot deletion, between `"none"` and `"tooltip"` and `"drop"` (see [Deletion Modes](#deletion-modes)).                                                                                             |
| `tooltipClassName`       | string                                                                                                  | null    | Class name to pass down to the deletion tooltip (see [Styles](#styles)).                                                                                                                                  |
| `tooltipContentSelector` | string                                                                                                  | null    | Selector of the deletion tooltip content (see [Customize the Content of the Deletion Tooltip](#customize-the-content-of-the-deletion-tooltip)).                                                           |
| `showTransparentSlot`    | boolean                                                                                                 | false   | Flag to display a transparent slot at the start of the slot list.                                                                                                                                         |
| `maxColors`              | number                                                                                                  | 30      | Maximum number of slots to be displayed in the palette. Set this value to `-1` to allow infinite number of slots.                                                                                         |
| `showInput`              | boolean                                                                                                 | false   | Flag to display the input within the footer slot.                                                                                                                                                         |
| `inputType`              | string                                                                                                  | "text"  | Type of the input within the footer slot. Only "text" and "color" are allowed. All other value will be replaced by "text".                                                                                |
| `numColumns`             | number                                                                                                  | 5       | Number of columns of the palette grid. This value can't exceed the number of maximum colors defined in `maxColors` and can't be lower than 1. Set this value to `0` to display the slots on a single row. |
| `maxColumns`             | number                                                                                                  | 0       | Maximum number of columns when `numColumns` is set to `0`. Once reached, additional slots wrap to a new row. Set this value to `0` to allow unlimited columns.                                            |
| `transition`             | object                                                                                                  | null    | Animation when a slot is rendered (see [Transition](#transition)).                                                                                                                                        |

## Callbacks

| Prop       | Arguments | Type   | Description                             |
| ---------- | --------- | ------ | --------------------------------------- |
| `onselect` |           |        | **Called whenever a color is clicked.** |
|            | `color`   | string | Selected color string.                  |

## Snippets

Snippets replace the Svelte 4 named slots API. Pass them as children of `<Palette>` using the `{#snippet name(props)}` syntax.

| Snippet           | Description                                                                           | Available Properties                                                      |
| ----------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `header`          | Allow to add a header to the palette. By default, it is empty.                        | `selectedColor`                                                           |
| `footer`          | Allow to add a footer to the palette. By default, it contains an input to add colors. | `selectedColor`                                                           |
| `slot`            | Allow to replace the default color slots.                                             | `index`, `color`, `colorName`, `selectedColor`, `transition`, `isCompact` |
| `transparentSlot` | Allow to replace the default transparent slot.                                        | -                                                                         |
| `beforeSlot`      | Allow to add an element before the color slots.                                       | `selectedColor`, `transition`, `isCompact`                                |
| `afterSlot`       | Allow to add an element after the color slots.                                        | `selectedColor`, `transition`, `isCompact`                                |
| `input`           | Allow to replace the input in the footer if the default footer snippet is kept as is. | `selectedColor`, `inputType`                                              |
| `settings`        | Allow to replace the settings panel. See the demo to grab a usage example.            | `onClose`                                                                 |
| `tools`           | Allow to replace the tools panel.                                                     | `isCompact`, `compactColorIndices`, `onSelect`                            |
| `loader`          | Allow to replace the loader displayed during the colors async retrieving.             | -                                                                         |

## Example

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']
</script>

<Palette {colors}>
	{#snippet header()}
		<div class="palette__header">
			<h1>Pick a color</h1>
		</div>
	{/snippet}
	{#snippet slot({ color })}
		<button class="palette__slot" style="--color:{color}"></button>
	{/snippet}
	{#snippet footer()}
		<div class="palette__footer">
			<a href="https://www.untemps.net">@untemps</a>
		</div>
	{/snippet}
</Palette>

.palette__slot {
		cursor: pointer;
		width: 2rem;
		height: 2rem;
		margin: 0;
		background-color: var(--color);
		border-radius: 20%;
		border: 1px solid rgba(0, 0, 0, 0.2);
		box-shadow: 0.1rem 0.1rem 0.3rem rgba(0, 0, 0, 0.2);
	}

.palette__footer {
		display: flex;
		justify-content: center;
		padding: 0.5rem;
	}
</style>
```

# Colors Setting

Color can be set in several formats:

## Array of Color Strings

```
colors = ['#865C54', '#8F5447', '#A65846']
```

## Array of Color Objects

```
colors = [
	{ name: 'Color #1', value: '#865C54' },
	{ name: 'Color #2', value: '#8F5447' },
	{ value: '#A65846' }
]
```

## Array of Color Groups

Colors can be organized into named groups by passing an array of `ColorGroup` objects:

```
colors = [
	{ name: 'Warm', colors: ['#865C54', '#8F5447', '#A65846'] },
	{ name: 'Cool', colors: ['#172B41', '#32465C', '#617899'] },
	{ colors: ['#8B8C6B', '#97A847'] }
]
```

Each group has:

- `name` (optional) — displayed as a label above the group
- `colors` — array of color strings or color objects

When groups are used, compact mode and the color input are not available. The `colorSlot` snippet receives an additional `groupName` parameter.

## Promise

A promise to be resolved with an array of color strings, objects, or groups can be passed as well (see [Use an API to fill the palette](#use-an-api-to-fill-the-palette))

# Deletion Modes

The `deletionMode` prop allows to define the way users can delete (or not) the color slots:

| Value     | Description                                                                                                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `none`    | (Default) Color slots cannot be deleted                                                                                                                                                    |
| `tooltip` | A tooltip is displayed when hovering a color slot, a click within deletes the slot <br/>(You can control tooltip display though the `tooltipClassName` and `tooltipContentSelector` props) |
| `drop`    | Colors slots are draggable, a drop outside the palette deletes the slot                                                                                                                    |

As an helper, deletion mode enums are exported in `PaletteDeletionMode`.

# Compact Mode

The compact mode is a way to display a minimal version of the palette with a restricted selection of the original colors and downsized spaces.

The `compactColorIndices` prop allows to define the list of the colors to be picked from the `colors` array by their indices.
If set a control is added to toggle the compact mode.

You may also specified whether the palette has to use the compact mode by default by setting `isCompact=true`.

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']
	const compactColorIndices = [1, 3, 4]
</script>

<Palette {colors} {compactColorIndices} />
```

# Styles

### Root Tag Class

You can style the component by passing a class down to the root tag (`div`).

- Flag the class as global to make it available in the Palette component
- Prefix your class with `.palette[role="main"]` to give precedence over the default one or mark each style with `!important` (not recommanded)

#### Example

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']
</script>

### Deletion Tooltip Class

If you set `deletionMode` to `"tooltip"`, you can pass a class name that is set to the tooltip shown when hovering a slot.

To do so, set a **global** class name to the `tooltipClassName` prop.

> As the tooltip is interactive, make sure you define a sufficient hover area that allow to access the content of the tooltip before the leave event is triggered.

If you ignore that prop, a default class is used.

> Please note that the default class name is `__tooltip__default`.
> Provide a different class name otherwise the default class would have the precedence over the custom one.

#### Example

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']
</script>

## EyeDropper API Support

If supported by the browser, the default component within the `input` snippet displays a button to trigger the [Web EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper).
The tool allows to pick a color from the screen.

Once selected, the color is inserted in the input waiting for the user to submit and adding it to the palette.

If the API is not available, nothing will be rendered.

> **Browser compatibility note:** The EyeDropper API specification defines `sRGBHex` as returning a hexadecimal color string (e.g. `#rrggbb`). However, some browsers return an `rgb()` or `rgba()` string instead. The component normalizes the value to hex format automatically.

> The `PaletteEyeDropperButton` component can be used on its own anywhere within a snippet or in an external component as it is exported from this lib:
>
> ```js
> import { PaletteEyeDropperButton } from '@untemps/svelte-palette'
> ```

## Transition

You can customize the way slots appear into the palette by using the `transition` prop.

This prop works the same way as the [in/out directive](https://svelte.dev/docs#template-syntax-element-directives-in-fn-out-fn) and accepts an object with two properties :

| Value  | Description                                                                                        |
| ------ | -------------------------------------------------------------------------------------------------- |
| `fn`   | Transition function (See [Svelte Transitions](https://svelte.dev/docs#run-time-svelte-transition)) |
| `args` | Parameters to pass to the transition function                                                      |

`fn` may be one of the [Svelte exported functions](https://svelte.dev/docs#run-time-svelte-transition) or a custom one as described in the [docs](https://svelte.dev/docs#template-syntax-element-directives-transition-fn-custom-transition-functions).

### Example

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'
	import { elasticOut } from 'svelte/easing'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']

const whoosh = (node, params) => {
		const existingTransform = getComputedStyle(node).transform.replace('none', '')

return {
			delay: params.delay || 0,
			duration: params.duration || 400,
			easing: params.easing || elasticOut,
			css: (t, u) => `transform: ${existingTransform} scale(${t})`,
		}
	}
</script>

<Palette {colors} transition={{ fn: whoosh, args: { duration: 3000 } }} />
```

## Recipes

### Use an API to Fill the Palette

In case you want to call an API to fetch the palette colors, you may pass a promise to the `colors` prop.

The component displays a customizable loader waiting to the promise to be resolved. Be aware that the result of the promise must be an array of color strings as well.

#### Example

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'

const colors = fetch('https://www.colr.org/json/colors/random/30')
		.then((result) => result.json())
		.then((result) => result.colors.filter((c) => c.hex?.length).map((c) => `#${c.hex}`))
</script>

<Palette {colors}>
	{#snippet loader()}
		<p>Loading...</p>
	{/snippet}
</Palette>
```

### Customize the Content of the Deletion Tooltip

By default, if `deletionMode` is set to `"tooltip"`, the tooltip displays a trash icon:

You may want to display a different content for various purposes.
That is possible by defining a DOM element selector to the `tooltipContentSelector` prop.

> Note the piece of DOM used ad content is deeply cloned using [cloneNode()](https://developer.mozilla.org/fr/docs/Web/API/Node/cloneNode) before appending to the tooltip container.
> That means the original element stays as it is but depending on element some props or behaviours may be removed from the clone.

#### Example

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']
</script>

<button class="palette__tooltip__button">Delete</button>
```

### Use a Color Input

By default, the input that allows to add a new slot in the palette is typed as "text".

Although you may use the `input` snippet to display a custom component, it is possible to turn the input into color mode by setting the `inputType` prop to "color".
That unlocks the color picker provided by the browser. Therefore the color spot and the eyedropper are hidden.

#### Example

```svelte
<script>
	import { Palette } from '@untemps/svelte-palette'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']
</script>

<Palette {colors} inputType="color" />
```

### Customize the Tools Panel

The tools panel is a container for two actions:

- Display the settings panel (`"settings"`)
- Toggle the compact mode (`"compact"`)

For some use cases, you may want to provide your own controls by using the `tools` snippet.

To access each tool behaviours, the Palette component exports a `onSelect` function that has to be called with the name of the tool (use the enums from the exported `PaletteTool`).

#### Example

```svelte
<script>
	import { Palette, PaletteTool } from '@untemps/svelte-palette'

const colors = ['#865C54', '#8F5447', '#A65846', '#A9715E', '#AD8C72']
</script>

<Palette {colors}>
	{#snippet tools({ onSelect, isCompact })}
		<div>
			<button onclick={() => onSelect(PaletteTool.SETTINGS)}>Settings</button>
			<button onclick={() => onSelect(PaletteTool.COMPACT)}>{isCompact ? 'Expand' : 'Compact'}</button>
		</div>
	{/snippet}
</Palette>
```

## Development

The component can be served for development purpose on `http://localhost:5173/` running:

```
yarn dev
```

## Contributing

Contributions are warmly welcomed:

- Fork the repository
- Create a feature branch
- Develop the feature AND write the tests (or write the tests AND develop the feature)
- Commit your changes
  using [Angular Git Commit Guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)
- Submit a Pull Request

svelte-palette

svelte-palette Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

svelte-palette

svelte-palette Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README