# salla-color-picker (https://docs.salla.dev/twilight/react/web-components/salla-color-picker)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

A color field: a swatch that opens a popup picker (powered by vanilla-picker) and stores the chosen color in a
hidden input, so it submits with the surrounding form. Use it for color-type product options or any form that needs
a color value. Also used by `salla-product-options` for color options.

The hidden input holds the hex value and gets a `change` event when the user clicks "Ok" in the popup. When `color`
is not set, it defaults to the theme primary color (`theme.color.primary`, falling back to `#5dd5c4`). The picker
loads lazily, so the methods wait for it to be ready.

## Use it [#use-it]

In HTML or JSX, use the tag `<salla-color-picker>` with the **Attribute** names below. In React, the wrapper takes the **Property** names (camelCase).

```tsx
import { SallaColorPicker } from '@salla.sa/twilight-components-react/color-picker';
```

## Try it [#try-it]

<Demo name="web-components/salla-color-picker" />

## Example [#example]

```tsx
import { useEffect } from 'react';
import { SallaColorPicker } from '@salla.sa/twilight-components-react/color-picker';

export function Example() {
  useEffect(() => {
    document.querySelector('salla-color-picker').addEventListener('submitted', e => console.log(e.detail.hex));
  }, []);

  return (
    <SallaColorPicker name="color" color="#ff6600" format="hex" enableAlpha />
  );
}
```

```html
<salla-color-picker name="color" color="#ff6600" format="hex" enable-alpha></salla-color-picker>
<script>
  document.querySelector('salla-color-picker').addEventListener('submitted', e => console.log(e.detail.hex));
</script>
```

## Properties [#properties]

| Property           | Attribute            | Description                                                                                                                                                                                                                                                                                         | Type                      | Default   |
| ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------- |
| `color`            | `color`              | Initial color. Accepts a color name or a hex, rgb(a) or hsl(a) string. Defaults to the theme primary color when empty. This prop is only set when the component loads and is not updated when the user picks a color; read the picked color from the `submitted` event or the hidden input instead. | `string`                  |           |
| `enableAlpha`      | `enable-alpha`       | Whether the popup lets the user adjust the alpha (opacity) channel.                                                                                                                                                                                                                                 | `boolean`                 | `false`   |
| `format`           | `format`             | How to display the selected color in the popup's text field (the field still accepts input in any format). Only has an effect when `showTextField` is true.                                                                                                                                         | `"hex" \| "hsl" \| "rgb"` | `'hex'`   |
| `name`             | `name`               | Name of the hidden input that holds the color, used as the key in the native form data.                                                                                                                                                                                                             | `string`                  | `'color'` |
| `required`         | `required`           | Marks the hidden input as required, so the surrounding form fails validation until a color is set.                                                                                                                                                                                                  | `boolean`                 | `false`   |
| `showCancelButton` | `show-cancel-button` | Whether to show a "Cancel" button in the popup that closes it.                                                                                                                                                                                                                                      | `boolean`                 | `false`   |
| `showTextField`    | `show-text-field`    | Whether to show a text field in the popup for editing the color value.                                                                                                                                                                                                                              | `boolean`                 | `true`    |

## Events [#events]

Listen with `addEventListener`, or the `on` prop of the React wrapper (for example `onModalBack`).

| Event          | Description                                                                                                                                                                              | Detail  |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `colorChanged` | Fires every time the color changes inside the popup, including while the user drags. `event.detail` is the color as `{ rgba, hsla, rgbString, rgbaString, hslString, hslaString, hex }`. | `Color` |
| `invalidInput` | Fires when the hidden input fails validation (for example `required` with no color). `event.detail` is the native `invalid` event.                                                       | `any`   |
| `popupClosed`  | Fires when the popup closes. `event.detail` is the current color, in the same shape as `colorChanged`.                                                                                   | `Color` |
| `popupOpened`  | Fires when the popup opens. `event.detail` is the current color, in the same shape as `colorChanged`.                                                                                    | `Color` |
| `submitted`    | Fires when the user clicks "Ok" in the popup. `event.detail` is the chosen color, in the same shape as `colorChanged`.                                                                   | `Color` |

## Methods [#methods]

Call these on the element or a React ref.

### `closePicker() => Promise<void>` [#closepicker--promisevoid]

Close the popup. Resolves with no value.

### `destroyPicker() => Promise<void>` [#destroypicker--promisevoid]

Release all resources used by the picker instance. The picker cannot be used afterwards.
Resolves with no value.

### `movePopUp(options: Options, openImmediately: boolean) => Promise<void>` [#movepopupoptions-options-openimmediately-boolean--promisevoid]

Move the popup to a different parent element, optionally opening it at the same time.

| Parameter         | Type      | Description                                                    |
| ----------------- | --------- | -------------------------------------------------------------- |
| `options`         | `Options` | New options for the popup, usually a new `parent` and `color`. |
| `openImmediately` | `boolean` | Whether to open the popup right after moving it.               |

### `openPicker() => Promise<void>` [#openpicker--promisevoid]

Open the popup. Resolves with no value.

### `setColorValue(color: string, triggerEvent: boolean) => Promise<void>` [#setcolorvaluecolor-string-triggerevent-boolean--promisevoid]

Set the picker's color. The swatch is not updated by this method; the hidden input is updated only when the change callback fires (see `triggerEvent`).

| Parameter      | Type      | Description                                                                                                                                                                               |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `color`        | `string`  | Color name or an RGBA, HSLA or HEX string.                                                                                                                                                |
| `triggerEvent` | `boolean` | Passed to vanilla-picker as its `silent` flag: when `true`, the change is applied without triggering the change callback (so `colorChanged` does not fire). Pass `false` to have it fire. |

### `setPickerOption(options: Options) => Promise<void>` [#setpickeroptionoptions-options--promisevoid]

Update the picker options, for example `color`. Accepts the vanilla-picker options.

| Parameter | Type      | Description                                                                 |
| --------- | --------- | --------------------------------------------------------------------------- |
| `options` | `Options` | Options to merge into the picker, such as `{ color: '#fff', alpha: true }`. |

## Slots [#slots]

| Slot     | Description                                                                            |
| -------- | -------------------------------------------------------------------------------------- |
| `widget` | Replaces the default swatch with arrow. The popup is anchored to the component itself. |

## Related [#related]

Used inside: [`<salla-product-options>`](https://docs.salla.dev/twilight/react/web-components/salla-product-options).