Automattic Design System

GradientPicker

GradientPicker is a React component that renders a color gradient picker to define a multi step gradient. There’s either a linear or a radial type available.

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

LinksPermalink to this section

View on Storybook

View source on GitHub

PropsPermalink to this section

Name	Default	Description
`className`		`string` The class name added to the wrapper.
`onChange` Required		`(currentGradient: string \| undefined, index?: number \| undefined, slug?: string \| undefined) => void` The function called when a new gradient has been defined. It is passed the `currentGradient` as an argument. When a predefined gradient is selected, the second argument is its index (or, for multiple-origin gradients, the origin index) and the third argument is its slug.
`value`	`'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'`	`string \| null \| undefined` The current value of the gradient. Pass a css gradient string (See default value for example). Optionally pass in a `null` value to specify no gradient is currently selected.
`selectedSlug`		`string` The slug of the currently selected predefined gradient. When set to a non-empty string, selection is determined by slug rather than by gradient value, which correctly handles palettes where two entries share the same gradient. Entries whose slug does not match will not appear selected in this mode, even if their gradient value matches `value`. An empty string is treated the same as `undefined`: selection falls back to matching by gradient value.
`clearable`	`true`	`boolean` Whether the palette should have a clearing button or not.
`headingLevel`	`2`	`1 \| 2 \| "1" \| 3 \| 4 \| 5 \| 6 \| "2" \| "3" \| "4" \| "5" \| "6"` The heading level. Only applies in cases where gradients are provided from multiple origins (i.e. when the array passed as the `gradients` prop contains two or more items).
`presentation`	`'listbox'`	`"listbox" \| "toggle-buttons" \| "command-buttons"` How predefined gradient 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 gradient picker.
`loop`	`true`	`boolean` Prevents keyboard interaction from wrapping around. Only used with the `listbox` presentation.
`enableAlpha`	`true`	`boolean` Whether to enable alpha transparency options in the picker.
`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.
`gradients`	`[]`	`GradientsProp \| undefined` An array of objects as predefined gradients displayed above the gradient selector. Alternatively, if there are multiple sets (or ‘origins’) of gradients, you can pass an array of objects each with a `name` and a `gradients` array which will in turn contain the predefined gradient objects.
`__nextHasNoMargin`	`false`	`boolean` Start opting in to the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 6.4. (The prop can be safely removed once this happens.)
`disableCustomGradients`	`false`	`boolean` If true, the gradient picker will not be displayed and only defined gradients from `gradients` will be shown.
`__experimentalIsRenderedInSidebar`	`false`	`boolean` Whether this is rendered in the sidebar.

ExamplesPermalink to this section

DefaultPermalink to this section

const Default = ( {
	onChange,
	value,
	selectedSlug,
	...props
}: React.ComponentProps< typeof GradientPicker > ) => {
	const [ gradient, setGradient ] = useState<
		React.ComponentProps< typeof GradientPicker >[ 'value' ]
	>( value ?? null );
	const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );
	return (
		<GradientPicker
			{ ...props }
			value={ gradient }
			selectedSlug={ slug }
			onChange={ ( currentGradient, index, newSlug ) => {
				setGradient( currentGradient );
				setSlug( newSlug );
				onChange?.( currentGradient, index, newSlug );
			} }
		/>
	);
};

With No Existing GradientsPermalink to this section

const WithNoExistingGradients = ( {
	onChange,
	value,
	selectedSlug,
	...props
}: React.ComponentProps< typeof GradientPicker > ) => {
	const [ gradient, setGradient ] = useState<
		React.ComponentProps< typeof GradientPicker >[ 'value' ]
	>( value ?? null );
	const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );
	return (
		<GradientPicker
			{ ...props }
			value={ gradient }
			selectedSlug={ slug }
			onChange={ ( currentGradient, index, newSlug ) => {
				setGradient( currentGradient );
				setSlug( newSlug );
				onChange?.( currentGradient, index, newSlug );
			} }
		/>
	);
};

Duplicate GradientsPermalink to this section

const DuplicateGradients = ( {
	onChange,
	value,
	selectedSlug,
	...props
}: React.ComponentProps< typeof GradientPicker > ) => {
	const [ gradient, setGradient ] = useState<
		React.ComponentProps< typeof GradientPicker >[ 'value' ]
	>( value ?? null );
	const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );
	return (
		<GradientPicker
			{ ...props }
			value={ gradient }
			selectedSlug={ slug }
			onChange={ ( currentGradient, index, newSlug ) => {
				setGradient( currentGradient );
				setSlug( newSlug );
				onChange?.( currentGradient, index, newSlug );
			} }
		/>
	);
};

Multiple OriginsPermalink to this section

const MultipleOrigins = ( {
	onChange,
	value,
	selectedSlug,
	...props
}: React.ComponentProps< typeof GradientPicker > ) => {
	const [ gradient, setGradient ] = useState<
		React.ComponentProps< typeof GradientPicker >[ 'value' ]
	>( value ?? null );
	const [ slug, setSlug ] = useState< string | undefined >( selectedSlug );
	return (
		<GradientPicker
			{ ...props }
			value={ gradient }
			selectedSlug={ slug }
			onChange={ ( currentGradient, index, newSlug ) => {
				setGradient( currentGradient );
				setSlug( newSlug );
				onChange?.( currentGradient, index, newSlug );
			} }
		/>
	);
};

CSS VariablesPermalink to this section

const CSSVariables = () => <div
    style={ {
        '--red': '#f00',
        '--yellow': '#ff0',
        '--blue': '#00f',
    } }>
    <Template
        onChange={fn()}
        gradients={[
			{
				name: 'Red to Yellow',
				gradient:
					'linear-gradient(135deg,var(--red) 0%,var(--yellow) 100%)',
				slug: 'red-to-yellow',
			},
			{
				name: 'Yellow to Blue',
				gradient:
					'linear-gradient(135deg,var(--yellow) 0%,var(--blue) 100%)',
				slug: 'yellow-to-blue',
			},
			{
				name: 'Blue to Red',
				gradient:
					'linear-gradient(135deg,var(--blue) 0%,var(--red) 100%)',
				slug: 'blue-to-red',
			},
		]} />
</div>;