---
name: ColorPalette
package: '@wordpress/components'
category: Forms
status: stable
canonical: 'https://system.automattic.design/components/colorpalette/'
storybook: 'https://wordpress.github.io/gutenberg/?path=/docs/components-colorpalette--docs'
github: 'https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/color-palette'
figma: 'https://www.figma.com/design/jMgzw8IhsMC4gpMbMko4lv/WPDS--Gutenberg-22.3-?node-id=16471-149532'
---

# ColorPalette

Allows the user to pick a color from a list of pre-defined color entries.

```tsx
import { ColorPalette } from '@wordpress/components';
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` *(required)* | `(newColor?: string \| undefined, index?: number \| undefined, slug?: string \| undefined) => void` | — | Callback called when a color is selected. The third argument is the slug of the selected palette entry, when available. |
| `selectedSlug` | `string` | — | The slug of the currently selected palette entry.<br>When set to a non-empty string, selection is determined by slug rather than by color value — this correctly handles palettes where two entries share the same color. Palette entries without a slug will not appear selected in this mode, even if their color value matches `value`.<br>An empty string is treated the same as `undefined`: selection falls back to matching by color value. |
| `clearable` | `boolean` | `true` | Whether the palette should have a clearing button. |
| `colors` | `PaletteObject[] \| ColorObject[] \| undefined` | `[]` | Array with the colors to be shown. When displaying multiple color palettes to choose from, the format of the array changes from an array of colors objects, to an array of color palettes. |
| `disableCustomColors` | `boolean` | `false` | Whether to allow the user to pick a custom color on top of the predefined choices (defined via the `colors` prop). |
| `enableAlpha` | `boolean` | `false` | This controls whether the alpha channel will be offered when selecting custom colors. |
| `headingLevel` | `1 \| 2 \| "1" \| 3 \| 4 \| 5 \| 6 \| "2" \| "3" \| "4" \| "5" \| "6"` | `2` | The heading level. |
| `value` | `string` | — | Currently active value. |
| `presentation` | `"listbox" \| "toggle-buttons" \| "command-buttons"` | `'listbox'` | How predefined color swatches behave and are exposed to assistive technology.<br>- `listbox` uses one tab stop and arrow-key navigation, and exposes   selection with `aria-selected`. - `toggle-buttons` gives each swatch a tab stop and exposes selection with   `aria-pressed`. - `command-buttons` gives each swatch a tab stop and exposes no selection   state. `value` and `selectedSlug` do not mark predefined swatches as   selected, and activating a swatch always calls `onChange` with that   swatch. `value` still controls the custom color picker. |
| `loop` | `boolean` | `true` | Prevents keyboard interaction from wrapping around. Only used with the `listbox` presentation. |
| `__experimentalIsRenderedInSidebar` | `boolean` | `false` | Whether this is rendered in the sidebar. |
| `aria-label` | `string` | — | A label to identify the purpose of the control. |
| `aria-labelledby` | `string` | — | An ID of an element to provide a label for the control. |
| `as` | `keyof IntrinsicElements \| JSXElementConstructor<any> \| undefined` | — | The HTML element or React component to render the component as. |


## Examples

### Default

```tsx
const Default = () => {
    const [ color, setColor ] = useState< string | undefined >( value );
    const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );

    return (
        <ColorPalette
            colors={[
                { name: 'Red', color: '#f00' },
                { name: 'White', color: '#fff' },
                { name: 'Blue', color: '#00f' },
            ]}
            value={ color }
            selectedSlug={ slug }
            onChange={ ( newColor, index, newSlug ) => {
				setColor( newColor );
				setSlug( newSlug );
				onChange?.( newColor, index, newSlug );
			} } />
    );
};
```

### Initial Value

```tsx
const InitialValue = () => {
    const [ color, setColor ] = useState< string | undefined >( value );
    const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );

    return (
        <ColorPalette
            colors={[
                { name: 'Red', color: '#f00' },
                { name: 'White', color: '#fff' },
                { name: 'Blue', color: '#00f' },
            ]}
            value={ color }
            selectedSlug={ slug }
            onChange={ ( newColor, index, newSlug ) => {
				setColor( newColor );
				setSlug( newSlug );
				onChange?.( newColor, index, newSlug );
			} } />
    );
};
```

### Multiple Origins

```tsx
const MultipleOrigins = () => {
    const [ color, setColor ] = useState< string | undefined >( value );
    const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );

    return (
        <ColorPalette
            colors={[
                {
                    name: 'Primary colors',
                    colors: [
                        { name: 'Red', color: '#f00' },
                        { name: 'Yellow', color: '#ff0' },
                        { name: 'Blue', color: '#00f' },
                    ],
                },
                {
                    name: 'Secondary colors',
                    colors: [
                        { name: 'Orange', color: '#f60' },
                        { name: 'Green', color: '#0f0' },
                        { name: 'Purple', color: '#60f' },
                    ],
                },
            ]}
            value={ color }
            selectedSlug={ slug }
            onChange={ ( newColor, index, newSlug ) => {
				setColor( newColor );
				setSlug( newSlug );
				onChange?.( newColor, index, newSlug );
			} } />
    );
};
```

### Duplicate Colors

```tsx
const DuplicateColors = () => {
    const [ color, setColor ] = useState< string | undefined >( value );
    const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );

    return (
        <ColorPalette
            colors={[
                { name: 'Dark Background', slug: 'dark-background', color: '#000' },
                { name: 'Dark Text', slug: 'dark-text', color: '#000' },
                { name: 'Brand', slug: 'brand', color: '#0073aa' },
            ]}
            value={ color }
            selectedSlug={ slug }
            onChange={ ( newColor, index, newSlug ) => {
				setColor( newColor );
				setSlug( newSlug );
				onChange?.( newColor, index, newSlug );
			} } />
    );
};
```

### CSS Variables

```tsx
const CSSVariables = () => <div
    style={ {
        '--red': '#f00',
        '--yellow': '#ff0',
        '--blue': '#00f',
    } }>
    <Template
        colors={[
			{ name: 'Red', color: 'var(--red)' },
			{ name: 'Yellow', color: 'var(--yellow)' },
			{ name: 'Blue', color: 'var(--blue)' },
		]} />
</div>;
```