Automattic Design System

ColorPalette

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

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

LinksPermalink to this section

View on Storybook

View source on GitHub

PropsPermalink to this section

Name	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. 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`. An empty string is treated the same as `undefined`: selection falls back to matching by color value.
`clearable`	`true`	`boolean` 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`	`false`	`boolean` Whether to allow the user to pick a custom color on top of the predefined choices (defined via the `colors` prop).
`enableAlpha`	`false`	`boolean` This controls whether the alpha channel will be offered when selecting custom colors.
`headingLevel`	`2`	`1 \| 2 \| "1" \| 3 \| 4 \| 5 \| 6 \| "2" \| "3" \| "4" \| "5" \| "6"` The heading level.
`value`		`string` Currently active value.
`presentation`	`'listbox'`	`"listbox" \| "toggle-buttons" \| "command-buttons"` How predefined color swatches behave and are exposed to assistive technology. `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`	`true`	`boolean` Prevents keyboard interaction from wrapping around. Only used with the `listbox` presentation.
`__experimentalIsRenderedInSidebar`	`false`	`boolean` 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.

ExamplesPermalink to this section

DefaultPermalink to this section

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 ValuePermalink to this section

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 OriginsPermalink to this section

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 ColorsPermalink to this section

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 VariablesPermalink to this section

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>;