Automattic Design System

Components /

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.

View on Storybook

View source on GitHub

Import

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

Props

NameTypeDefaultRequiredDescription
classNamestring

The class name added to the wrapper.

onChange( currentGradient: string | undefined ) => voidYes

The function called when a new gradient has been defined. It is passed to the currentGradient as an argument.

valueGradientObject[ 'gradient' ] | null

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.

@default ‘linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)’

clearablebooleantrue

Whether the palette should have a clearing button or not.

@default true

headingLevel| 1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'2

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).

@default 2

asButtonsboolean

Whether the control should present as a set of buttons, each with its own tab stop.

@default false

loopboolean

Prevents keyboard interaction from wrapping around. Only used when asButtons is not true.

@default true

enableAlphabooleantrue

Whether to enable alpha transparency options in the picker.

@default true

gradientsGradientObject[] | OriginObject[][]

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.

@default []

disableCustomGradientsbooleanfalse

If true, the gradient picker will not be displayed and only defined gradients from gradients will be shown.

@default false

__experimentalIsRenderedInSidebarboolean

Whether this is rendered in the sidebar.

@default false

Examples

Default

const Default = ( {
	onChange,
	...props
}: React.ComponentProps< typeof GradientPicker > ) => {
	const [ gradient, setGradient ] =
		useState< ( typeof props )[ 'value' ] >( null );
	return (
		<GradientPicker
			{ ...props }
			value={ gradient }
			onChange={ ( ...changeArgs ) => {
				setGradient( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
		/>
	);
};

With No Existing Gradients

const WithNoExistingGradients = ( {
	onChange,
	...props
}: React.ComponentProps< typeof GradientPicker > ) => {
	const [ gradient, setGradient ] =
		useState< ( typeof props )[ 'value' ] >( null );
	return (
		<GradientPicker
			{ ...props }
			value={ gradient }
			onChange={ ( ...changeArgs ) => {
				setGradient( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
		/>
	);
};

Multiple Origins

const MultipleOrigins = ( {
	onChange,
	...props
}: React.ComponentProps< typeof GradientPicker > ) => {
	const [ gradient, setGradient ] =
		useState< ( typeof props )[ 'value' ] >( null );
	return (
		<GradientPicker
			{ ...props }
			value={ gradient }
			onChange={ ( ...changeArgs ) => {
				setGradient( ...changeArgs );
				onChange?.( ...changeArgs );
			} }
		/>
	);
};

CSS Variables

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