---
name: GradientPicker
package: '@wordpress/components'
category: '@wordpress-components'
status: stable
canonical: 'https://system.automattic.design/components/gradientpicker/'
storybook: 'https://wordpress.github.io/gutenberg/?path=/docs/components-gradientpicker--docs'
github: 'https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/gradient-picker'
figma: 'https://www.figma.com/design/jMgzw8IhsMC4gpMbMko4lv/WPDS--Gutenberg-22.3-?node-id=16530-42457'
---

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

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

## Props

| Name | Type | 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` | `string \| null \| undefined` | `'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)'` | 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.<br>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`.<br>An empty string is treated the same as `undefined`: selection falls back to matching by gradient value. |
| `clearable` | `boolean` | `true` | Whether the palette should have a clearing button or not. |
| `headingLevel` | `2 \| 1 \| "1" \| "2" \| "3" \| 3 \| 4 \| 5 \| 6 \| "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). |
| `presentation` | `"listbox" \| "toggle-buttons" \| "command-buttons"` | `'listbox'` | How predefined gradient 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 gradient picker. |
| `loop` | `boolean` | `true` | Prevents keyboard interaction from wrapping around. Only used with the `listbox` presentation. |
| `enableAlpha` | `boolean` | `true` | 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` | `boolean` | `false` | 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` | `boolean` | `false` | If true, the gradient picker will not be displayed and only defined gradients from `gradients` will be shown. |
| `__experimentalIsRenderedInSidebar` | `boolean` | `false` | Whether this is rendered in the sidebar. |


## Examples

### Default

```tsx
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 Gradients

```tsx
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 Gradients

```tsx
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 Origins

```tsx
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 Variables

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