ColorSwatchPicker

A ColorSwatchPicker displays a list of color swatches and allows a user to select one of them.

install	`yarn add react-aria-components`
version	1.4.0
usage	`import {ColorSwatchPicker} from 'react-aria-components'`

View ARIA pattern

W3C

Example#

import {ColorSwatch, ColorSwatchPicker, ColorSwatchPickerItem} from 'react-aria-components';

<ColorSwatchPicker>
  <ColorSwatchPickerItem color="#A00">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#f80">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#080">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#08f">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#088">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#008">
    <ColorSwatch />
  </ColorSwatchPickerItem>
</ColorSwatchPicker>

import {
  ColorSwatch,
  ColorSwatchPicker,
  ColorSwatchPickerItem
} from 'react-aria-components';

<ColorSwatchPicker>
  <ColorSwatchPickerItem color="#A00">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#f80">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#080">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#08f">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#088">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#008">
    <ColorSwatch />
  </ColorSwatchPickerItem>
</ColorSwatchPicker>

import {
  ColorSwatch,
  ColorSwatchPicker,
  ColorSwatchPickerItem
} from 'react-aria-components';

<ColorSwatchPicker>
  <ColorSwatchPickerItem color="#A00">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#f80">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#080">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#08f">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#088">
    <ColorSwatch />
  </ColorSwatchPickerItem>
  <ColorSwatchPickerItem color="#008">
    <ColorSwatch />
  </ColorSwatchPickerItem>
</ColorSwatchPicker>

Show CSS

@import "@react-aria/example-theme";

.react-aria-ColorSwatchPicker {
  display: flex;
  gap: 8px;
  flex-wrap: wrap;
}

.react-aria-ColorSwatchPickerItem {
  position: relative;
  outline: none;
  border-radius: 4px;
  width: fit-content;
  forced-color-adjust: none;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: 2px;
  }

  &[data-selected]::after {
    content: '';
    position: absolute;
    inset: 0;
    border: 2px solid black;
    outline: 2px solid white;
    outline-offset: -4px;
    border-radius: inherit;
  }
}

@import "@react-aria/example-theme";

.react-aria-ColorSwatchPicker {
  display: flex;
  gap: 8px;
  flex-wrap: wrap;
}

.react-aria-ColorSwatchPickerItem {
  position: relative;
  outline: none;
  border-radius: 4px;
  width: fit-content;
  forced-color-adjust: none;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: 2px;
  }

  &[data-selected]::after {
    content: '';
    position: absolute;
    inset: 0;
    border: 2px solid black;
    outline: 2px solid white;
    outline-offset: -4px;
    border-radius: inherit;
  }
}

@import "@react-aria/example-theme";

.react-aria-ColorSwatchPicker {
  display: flex;
  gap: 8px;
  flex-wrap: wrap;
}

.react-aria-ColorSwatchPickerItem {
  position: relative;
  outline: none;
  border-radius: 4px;
  width: fit-content;
  forced-color-adjust: none;

  &[data-focus-visible] {
    outline: 2px solid var(--focus-ring-color);
    outline-offset: 2px;
  }

  &[data-selected]::after {
    content: '';
    position: absolute;
    inset: 0;
    border: 2px solid black;
    outline: 2px solid white;
    outline-offset: -4px;
    border-radius: inherit;
  }
}

Features#

A ColorSwatchPicker wraps the ListBox component to simplify building color swatch pickers that work with a ColorPicker.

Item selection – A single color value can be selected from a list of unique colors. Color swatches are automatically matched with the value no matter the color space they are defined in.
Keyboard navigation – Color swatches can be navigated using the arrow keys, along with page up/down, home/end, etc.
Layout options – Items can be arranged in a vertical or horizontal stack, or as a two-dimensional grid.
Accessible – Follows the ARIA listbox pattern. Each swatch includes a localized color description for screen reader users (e.g. "dark vibrant blue").
Styleable – Items include builtin states for styling, such as hover, press, focus, selected, and disabled.

Anatomy#

A ColorSwatchPicker consists of a container element, with a list of color swatches inside. Users can select a color by clicking, tapping, or navigating with the keyboard.

import {ColorSwatch, ColorSwatchPicker, ColorSwatchPickerItem} from 'react-aria-components';

<ColorSwatchPicker>
  <ColorSwatchPickerItem>
    <ColorSwatch />
  </ColorSwatchPickerItem>
</ColorSwatchPicker>

import {
  ColorSwatch,
  ColorSwatchPicker,
  ColorSwatchPickerItem
} from 'react-aria-components';

<ColorSwatchPicker>
  <ColorSwatchPickerItem>
    <ColorSwatch />
  </ColorSwatchPickerItem>
</ColorSwatchPicker>

import {
  ColorSwatch,
  ColorSwatchPicker,
  ColorSwatchPickerItem
} from 'react-aria-components';

<ColorSwatchPicker>
  <ColorSwatchPickerItem>
    <ColorSwatch />
  </ColorSwatchPickerItem>
</ColorSwatchPicker>

ColorSwatchPicker is a convenience wrapper around the ListBox component. If you need additional flexibility, such as support for multiple selection, duplicate colors, drag and drop, etc., you can use the ListBox component directly.

Starter kits#

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured Storybook that you can experiment with, or use as a starting point for your own component library.

Reusable wrappers#

If you will use a ColorSwatchPicker in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

This example wraps ColorSwatchPicker and ColorSwatchPickerItem, reusing the MyColorSwatch component from the ColorSwatch docs.

import type {ColorSwatchPickerItemProps, ColorSwatchPickerProps} from 'react-aria-components';
import {MyColorSwatch} from './ColorSwatch';

export function MyColorSwatchPicker(
  { children, ...props }: ColorSwatchPickerProps
) {
  return (
    <ColorSwatchPicker {...props}>
      {children}
    </ColorSwatchPicker>
  );
}

export function MyColorSwatchPickerItem(props: ColorSwatchPickerItemProps) {
  return (
    <ColorSwatchPickerItem {...props}>
      <MyColorSwatch />
    </ColorSwatchPickerItem>
  );
}

<MyColorSwatchPicker>
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
  <MyColorSwatchPickerItem color="#08f" />
  <MyColorSwatchPickerItem color="#088" />
  <MyColorSwatchPickerItem color="#008" />
</MyColorSwatchPicker>

import type {
  ColorSwatchPickerItemProps,
  ColorSwatchPickerProps
} from 'react-aria-components';
import {MyColorSwatch} from './ColorSwatch';

export function MyColorSwatchPicker(
  { children, ...props }: ColorSwatchPickerProps
) {
  return (
    <ColorSwatchPicker {...props}>
      {children}
    </ColorSwatchPicker>
  );
}

export function MyColorSwatchPickerItem(
  props: ColorSwatchPickerItemProps
) {
  return (
    <ColorSwatchPickerItem {...props}>
      <MyColorSwatch />
    </ColorSwatchPickerItem>
  );
}

<MyColorSwatchPicker>
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
  <MyColorSwatchPickerItem color="#08f" />
  <MyColorSwatchPickerItem color="#088" />
  <MyColorSwatchPickerItem color="#008" />
</MyColorSwatchPicker>

import type {
  ColorSwatchPickerItemProps,
  ColorSwatchPickerProps
} from 'react-aria-components';
import {MyColorSwatch} from './ColorSwatch';

export function MyColorSwatchPicker(
  { children, ...props }:
    ColorSwatchPickerProps
) {
  return (
    <ColorSwatchPicker
      {...props}
    >
      {children}
    </ColorSwatchPicker>
  );
}

export function MyColorSwatchPickerItem(
  props:
    ColorSwatchPickerItemProps
) {
  return (
    <ColorSwatchPickerItem
      {...props}
    >
      <MyColorSwatch />
    </ColorSwatchPickerItem>
  );
}

<MyColorSwatchPicker>
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
  <MyColorSwatchPickerItem color="#08f" />
  <MyColorSwatchPickerItem color="#088" />
  <MyColorSwatchPickerItem color="#008" />
</MyColorSwatchPicker>

Value#

ColorSwatchPicker accepts either an uncontrolled default value or a controlled value, provided using the defaultValue or value props respectively. The value provided to either of these props should be a color string or Color object. The value is matched against the color of each ColorSwatch, including equivalent colors in different color spaces.

In the example below, the parseColor function is used to parse the initial color from a HSL string so that value's type remains consistent.

import {parseColor} from 'react-aria-components';

function Example() {
  let [color, setColor] = React.useState(parseColor('hsl(0, 100%, 33.33%)'));

  return (
    <MyColorSwatchPicker value={color} onChange={setColor}>
      <MyColorSwatchPickerItem color="#A00" />
      <MyColorSwatchPickerItem color="#f80" />
      <MyColorSwatchPickerItem color="#080" />
    </MyColorSwatchPicker>
  );
}

import {parseColor} from 'react-aria-components';

function Example() {
  let [color, setColor] = React.useState(
    parseColor('hsl(0, 100%, 33.33%)')
  );

  return (
    <MyColorSwatchPicker value={color} onChange={setColor}>
      <MyColorSwatchPickerItem color="#A00" />
      <MyColorSwatchPickerItem color="#f80" />
      <MyColorSwatchPickerItem color="#080" />
    </MyColorSwatchPicker>
  );
}

import {parseColor} from 'react-aria-components';

function Example() {
  let [color, setColor] =
    React.useState(
      parseColor(
        'hsl(0, 100%, 33.33%)'
      )
    );

  return (
    <MyColorSwatchPicker
      value={color}
      onChange={setColor}
    >
      <MyColorSwatchPickerItem color="#A00" />
      <MyColorSwatchPickerItem color="#f80" />
      <MyColorSwatchPickerItem color="#080" />
    </MyColorSwatchPicker>
  );
}

Note: ColorSwatches rendered inside a ColorSwatchPicker must have unique colors, even between different color spaces. For example, the values #f00, hsl(0, 100%, 50%), and hsb(0, 100%, 100%) are all equivalent and considered duplicates. This is required so that selection behavior works properly.

Labeling#

By default, ColorSwatchPicker has an aria-label with the localized string "Color swatches". This can be overridden with a more specific accessibility label using the aria-label or aria-labelledby props. All labels should be localized.

<MyColorSwatchPicker aria-label="Fill color">
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
</MyColorSwatchPicker>

<MyColorSwatchPicker aria-label="Fill color">
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
</MyColorSwatchPicker>

<MyColorSwatchPicker aria-label="Fill color">
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
</MyColorSwatchPicker>

Events#

ColorSwatchPicker accepts an onChange prop which is triggered whenever the value is edited by the user. It receives a Color object as a parameter.

The example below uses onChange to update a separate element with the color value as a string.

import {parseColor} from 'react-aria-components';

function Example() {
  let [value, setValue] = React.useState(parseColor('#A00'));

  return (
    <div>
      <MyColorSwatchPicker value={value} onChange={setValue}>
        <MyColorSwatchPickerItem color="#A00" />
        <MyColorSwatchPickerItem color="#f80" />
        <MyColorSwatchPickerItem color="#080" />
        <MyColorSwatchPickerItem color="#08f" />
        <MyColorSwatchPickerItem color="#088" />
        <MyColorSwatchPickerItem color="#008" />
      </MyColorSwatchPicker>
      <p>Selected color: {value.toString('rgb')}</p>
    </div>
  );
}

import {parseColor} from 'react-aria-components';

function Example() {
  let [value, setValue] = React.useState(
    parseColor('#A00')
  );

  return (
    <div>
      <MyColorSwatchPicker
        value={value}
        onChange={setValue}
      >
        <MyColorSwatchPickerItem color="#A00" />
        <MyColorSwatchPickerItem color="#f80" />
        <MyColorSwatchPickerItem color="#080" />
        <MyColorSwatchPickerItem color="#08f" />
        <MyColorSwatchPickerItem color="#088" />
        <MyColorSwatchPickerItem color="#008" />
      </MyColorSwatchPicker>
      <p>Selected color: {value.toString('rgb')}</p>
    </div>
  );
}

import {parseColor} from 'react-aria-components';

function Example() {
  let [value, setValue] =
    React.useState(
      parseColor('#A00')
    );

  return (
    <div>
      <MyColorSwatchPicker
        value={value}
        onChange={setValue}
      >
        <MyColorSwatchPickerItem color="#A00" />
        <MyColorSwatchPickerItem color="#f80" />
        <MyColorSwatchPickerItem color="#080" />
        <MyColorSwatchPickerItem color="#08f" />
        <MyColorSwatchPickerItem color="#088" />
        <MyColorSwatchPickerItem color="#008" />
      </MyColorSwatchPicker>
      <p>
        Selected color:
        {' '}
        {value.toString(
          'rgb'
        )}
      </p>
    </div>
  );
}

Disabled#

A ColorSwatchPickerItem can be disabled using the isDisabled prop. Disabled swatches cannot be selected, and are not focusable or interactive.

<MyColorSwatchPicker>
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" isDisabled />
  <MyColorSwatchPickerItem color="#080" />
</MyColorSwatchPicker>

<MyColorSwatchPicker>
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" isDisabled />
  <MyColorSwatchPickerItem color="#080" />
</MyColorSwatchPicker>

<MyColorSwatchPicker>
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem
    color="#f80"
    isDisabled
  />
  <MyColorSwatchPickerItem color="#080" />
</MyColorSwatchPicker>

Show CSS

.react-aria-ColorSwatchPickerItem {
  &[data-disabled] {
    opacity: 0.2;
  }
}

.react-aria-ColorSwatchPickerItem {
  &[data-disabled] {
    opacity: 0.2;
  }
}

.react-aria-ColorSwatchPickerItem {
  &[data-disabled] {
    opacity: 0.2;
  }
}

Stack layout#

By default, ColorSwatchPicker expects items to be arranged horizontally, optionally wrapping to form a grid, and implements keyboard navigation and drag and drop accordingly. The layout prop can be used to display the swatches as a vertical stack instead.

<MyColorSwatchPicker layout="stack">
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
  <MyColorSwatchPickerItem color="#08f" />
  <MyColorSwatchPickerItem color="#088" />
  <MyColorSwatchPickerItem color="#008" />
</MyColorSwatchPicker>

<MyColorSwatchPicker layout="stack">
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
  <MyColorSwatchPickerItem color="#08f" />
  <MyColorSwatchPickerItem color="#088" />
  <MyColorSwatchPickerItem color="#008" />
</MyColorSwatchPicker>

<MyColorSwatchPicker layout="stack">
  <MyColorSwatchPickerItem color="#A00" />
  <MyColorSwatchPickerItem color="#f80" />
  <MyColorSwatchPickerItem color="#080" />
  <MyColorSwatchPickerItem color="#08f" />
  <MyColorSwatchPickerItem color="#088" />
  <MyColorSwatchPickerItem color="#008" />
</MyColorSwatchPicker>

Show CSS

.react-aria-ColorSwatchPicker {
  &[data-layout=stack] {
    flex-direction: column;
  }
}

.react-aria-ColorSwatchPicker {
  &[data-layout=stack] {
    flex-direction: column;
  }
}

.react-aria-ColorSwatchPicker {
  &[data-layout=stack] {
    flex-direction: column;
  }
}

Props#

ColorSwatchPicker#

Name	Type	Default	Description
`children`	`ReactNode`	—	The children of the ColorSwatchPicker.
`layout`	`'grid' \| 'stack'`	`'grid'`	Whether the items are arranged in a stack or grid.
`value`	`string \| Color`	—	The current value (controlled).
`defaultValue`	`string \| Color`	—	The default value (uncontrolled).
`className`	`string \| ( (values: ColorSwatchPickerRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ColorSwatchPickerRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onChange`	`( (value: Color )) => void`	Handler that is called when the value changes.

Accessibility

Name	Type	Description
`aria-label`	`string`	Defines a string value that labels the current element.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element (or elements) that provide a detailed, extended description for the object.

ColorSwatchPickerItem#

A <ColorSwatchPickerItem> represents an individual item within a <ColorSwatchPicker>. It should contain a <ColorSwatch>.

Name	Type	Description
`color`	`string \| Color`	The color of the swatch.
`isDisabled`	`boolean`	Whether the color swatch is disabled.
`children`	`ReactNode \| ( (values: ColorSwatchPickerItemRenderProps & & {defaultChildren: ReactNode \| \| undefined } )) => ReactNode`	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string \| ( (values: ColorSwatchPickerItemRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ColorSwatchPickerItemRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	The inline style for the element. A function may be provided to compute the style based on component state.

Events

Name	Type	Description
`onHoverStart`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction starts.
`onHoverEnd`	`( (e: HoverEvent )) => void`	Handler that is called when a hover interaction ends.
`onHoverChange`	`( (isHovering: boolean )) => void`	Handler that is called when the hover state changes.

Styling#

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin className attribute which can be targeted using CSS selectors. These follow the react-aria-ComponentName naming convention.

.react-aria-ColorSwatchPicker {
  /* ... */
}

.react-aria-ColorSwatchPicker {
  /* ... */
}

.react-aria-ColorSwatchPicker {
  /* ... */
}

A custom className can also be specified on any component. This overrides the default className provided by React Aria with your own.

<ColorSwatchPicker className="my-color-swatch-picker">
  {/* ... */}
</ColorSwatchPicker>

<ColorSwatchPicker className="my-color-swatch-picker">
  {/* ... */}
</ColorSwatchPicker>

<ColorSwatchPicker className="my-color-swatch-picker">
  {/* ... */}
</ColorSwatchPicker>

In addition, some components support multiple UI states (e.g. focused, placeholder, readonly, etc.). React Aria components expose states using data attributes, which you can target in CSS selectors. For example:

.react-aria-ColorSwatchPickerItem[data-selected] {
  /* ... */
}

.react-aria-ColorSwatchPickerItem[data-selected] {
  /* ... */
}

.react-aria-ColorSwatchPickerItem[data-selected] {
  /* ... */
}

The className and style props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like Tailwind.

<ColorSwatchPickerItem
  className={({ isSelected }) =>
    isSelected ? 'border-black' : 'border-transparent'}
/>

<ColorSwatchPickerItem
  className={({ isSelected }) =>
    isSelected ? 'border-black' : 'border-transparent'}
/>

<ColorSwatchPickerItem
  className={(
    { isSelected }
  ) =>
    isSelected
      ? 'border-black'
      : 'border-transparent'}
/>

The states, selectors, and render props for each component used in a ColorSwatchPicker are documented below.

ColorSwatchPicker#

The ColorSwatchPicker component can be targeted with the .react-aria-ColorSwatchPicker CSS selector, or by overriding with a custom className. It supports the following states:

Name	CSS Selector	Description
`isEmpty`	`[data-empty]`	Whether the listbox has no items and should display its empty state.
`isFocused`	`[data-focused]`	Whether the listbox is currently focused.
`isFocusVisible`	`[data-focus-visible]`	Whether the listbox is currently keyboard focused.
`layout`	`[data-layout="stack \| grid"]`	Whether the items are arranged in a stack or grid.
`state`	`—`	State of the listbox.

ColorSwatchPickerItem#

The ColorSwatchPickerItem component can be targeted with the .react-aria-ColorSwatchPickerItem CSS selector, or by overriding with a custom className. It supports the following states:

Name	CSS Selector	Description
`color`	`—`	The color of the swatch.
`isHovered`	`[data-hovered]`	Whether the item is currently hovered with a mouse.
`isPressed`	`[data-pressed]`	Whether the item is currently in a pressed state.
`isSelected`	`[data-selected]`	Whether the item is currently selected.
`isFocused`	`[data-focused]`	Whether the item is currently focused.
`isFocusVisible`	`[data-focus-visible]`	Whether the item is currently keyboard focused.
`isDisabled`	`[data-disabled]`	Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.

ColorSwatch#

The ColorSwatch component can be targeted with the .react-aria-ColorSwatch CSS selector, or by overriding with a custom className. It supports the following states:

Name	Description
`color`	The color of the swatch.

Advanced customization#

Composition#

If you need to customize one of the components within a ColorSwatchPicker, such as ColorSwatchPickerItem or ColorSwatch, in many cases you can create a wrapper component. This lets you customize the props passed to the component.

function MyColorSwatchPickerItem(props) {
  return <ColorSwatchPickerItem {...props} className="my-swatch" />
}

function MyColorSwatchPickerItem(props) {
  return (
    <ColorSwatchPickerItem
      {...props}
      className="my-swatch"
    />
  );
}

function MyColorSwatchPickerItem(
  props
) {
  return (
    <ColorSwatchPickerItem
      {...props}
      className="my-swatch"
    />
  );
}

Contexts#

All React Aria Components export a corresponding context that can be used to send props to them from a parent element. This enables you to build your own compositional APIs similar to those found in React Aria Components itself. You can send any prop or ref via context that you could pass to the corresponding component. The local props and ref on the component are merged with the ones passed via context, with the local props taking precedence (following the rules documented in mergeProps).

Component	Context	Props	Ref
`ColorSwatchPicker`	`ColorSwatchPickerContext`	`ColorSwatchPickerProps`	`HTMLDivElement`

This example shows how to synchronize a ColorSwatchPicker and a ColorField via context.

import {ColorSwatchPickerContext} from 'react-aria-components';
import {MyColorField} from './ColorField';

function ColorSelector({children}) {
  let [value, setValue] = React.useState(parseColor('#A00'));
  return (
    <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
      <MyColorField label="Color" value={value} onChange={setValue} />
      <ColorSwatchPickerContext.Provider value={{value, onChange: setValue}}>
        {children}
      </ColorSwatchPickerContext.Provider>    </div>
  );
}

<ColorSelector>
  <MyColorSwatchPicker>
    <MyColorSwatchPickerItem color="#A00" />
    <MyColorSwatchPickerItem color="#f80" />
    <MyColorSwatchPickerItem color="#080" />
  </MyColorSwatchPicker>
</ColorSelector>

import {ColorSwatchPickerContext} from 'react-aria-components';
import {MyColorField} from './ColorField';

function ColorSelector({ children }) {
  let [value, setValue] = React.useState(
    parseColor('#A00')
  );
  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        gap: 8
      }}
    >
      <MyColorField
        label="Color"
        value={value}
        onChange={setValue}
      />
      <ColorSwatchPickerContext.Provider
        value={{ value, onChange: setValue }}
      >
        {children}
      </ColorSwatchPickerContext.Provider>    </div>
  );
}

<ColorSelector>
  <MyColorSwatchPicker>
    <MyColorSwatchPickerItem color="#A00" />
    <MyColorSwatchPickerItem color="#f80" />
    <MyColorSwatchPickerItem color="#080" />
  </MyColorSwatchPicker>
</ColorSelector>

import {ColorSwatchPickerContext} from 'react-aria-components';
import {MyColorField} from './ColorField';

function ColorSelector(
  { children }
) {
  let [value, setValue] =
    React.useState(
      parseColor('#A00')
    );
  return (
    <div
      style={{
        display: 'flex',
        flexDirection:
          'column',
        gap: 8
      }}
    >
      <MyColorField
        label="Color"
        value={value}
        onChange={setValue}
      />
      <ColorSwatchPickerContext.Provider
        value={{
          value,
          onChange:
            setValue
        }}
      >
        {children}
      </ColorSwatchPickerContext.Provider>    </div>
  );
}

<ColorSelector>
  <MyColorSwatchPicker>
    <MyColorSwatchPickerItem color="#A00" />
    <MyColorSwatchPickerItem color="#f80" />
    <MyColorSwatchPickerItem color="#080" />
  </MyColorSwatchPicker>
</ColorSelector>

Represents a color value.

Method	Description
`toFormat( (format: ColorFormat )): Color`	Converts the color to the given color format, and returns a new Color object.
`toString( (format?: ColorFormat \| \| 'css' )): string`	Converts the color to a string in the given format.
`clone(): Color`	Returns a duplicate of the color value.
`toHexInt(): number`	Converts the color to hex, and returns an integer representation.
`getChannelValue( (channel: ColorChannel )): number`	Returns the numeric value for a given channel. Throws an error if the channel is unsupported in the current color format.
`withChannelValue( (channel: ColorChannel, , value: number )): Color`	Sets the numeric value for a given channel, and returns a new Color object. Throws an error if the channel is unsupported in the current color format.
`getChannelRange( (channel: ColorChannel )): ColorChannelRange`	Returns the minimum, maximum, and step values for a given channel.
`getChannelName( (channel: ColorChannel, , locale: string )): string`	Returns a localized color channel name for a given channel and locale, for use in visual or accessibility labels.
`getChannelFormatOptions( (channel: ColorChannel )): Intl.NumberFormatOptions`	Returns the number formatting options for the given channel.
`formatChannelValue( (channel: ColorChannel, , locale: string )): string`	Formats the numeric value for a given channel for display according to the provided locale.
`getColorSpace(): ColorSpace`	Returns the color space, 'rgb', 'hsb' or 'hsl', for the current color.
`getColorSpaceAxes( (xyChannels: {xChannel?: ColorChannel, yChannel?: ColorChannel } )): ColorAxes`	Returns the color space axes, xChannel, yChannel, zChannel.
`getColorChannels(): [ ColorChannel, ColorChannel, ColorChannel ]`	Returns an array of the color channels within the current color space space.
`getColorName( (locale: string )): string`	Returns a localized name for the color, for use in visual or accessibility labels.
`getHueName( (locale: string )): string`	Returns a localized name for the hue, for use in visual or accessibility labels.

A list of supported color formats.

'hex'
  | 'hexa'
  | 'rgb'
  | 'rgba'
  | 'hsl'
  | 'hsla'
  | 'hsb'
  | 'hsba'

A list of color channels.

'hue'
  | 'saturation'
  | 'brightness'
  | 'lightness'
  | 'red'
  | 'green'
  | 'blue'
  | 'alpha'

Name	Type	Description
`minValue`	`number`	The minimum value of the color channel.
`maxValue`	`number`	The maximum value of the color channel.
`step`	`number`	The step value of the color channel, used when incrementing and decrementing.
`pageSize`	`number`	The page step value of the color channel, used when incrementing and decrementing.

'rgb'
  | 'hsl'
  | 'hsb'

{xChannel: ColorChannel,
yChannel: ColorChannel,
zChannel: ColorChannel
}

Parses a color from a string value. Throws an error if the string could not be parsed.

parseColor(
  (value: string
)): Color

Name	Type	Description
`isEmpty`	`boolean`	Whether the listbox has no items and should display its empty state.
`isFocused`	`boolean`	Whether the listbox is currently focused.
`isFocusVisible`	`boolean`	Whether the listbox is currently keyboard focused.
`layout`	`'stack' \| 'grid'`	Whether the items are arranged in a stack or grid.
`state`	`ListState<unknown>`	State of the listbox.

Name	Type	Description
`collection`	`Collection<Node<T>>`	A collection of items in the list.
`disabledKeys`	`Set<Key>`	A set of items that are disabled.
`selectionManager`	`SelectionManager`	A selection manager to read and update multiple selection state.

A generic interface to access a readonly sequential collection of unique keyed items.

Extends: Iterable

Properties

Name	Type	Description
`size`	`number`	The number of items in the collection.

Methods

Method	Description
`getKeys(): Iterable<Key>`	Iterate over all keys in the collection.
`getItem( (key: Key )): T \| null`	Get an item by its key.
`at( (idx: number )): T \| null`	Get an item by the index of its key.
`getKeyBefore( (key: Key )): Key \| null`	Get the key that comes before the given key in the collection.
`getKeyAfter( (key: Key )): Key \| null`	Get the key that comes after the given key in the collection.
`getFirstKey(): Key \| null`	Get the first key in the collection.
`getLastKey(): Key \| null`	Get the last key in the collection.
`getChildren( (key: Key )): Iterable<T>`	Iterate over the child items of the given key.
`getTextValue( (key: Key )): string`	Returns a string representation of the item's contents.

Name	Type	Description
`type`	`string`	The type of item this node represents.
`key`	`Key`	A unique key for the node.
`value`	`T \| null`	The object value the node was created from.
`level`	`number`	The level of depth this node is at in the hierarchy.
`hasChildNodes`	`boolean`	Whether this item has children, even if not loaded yet.
`rendered`	`ReactNode`	The rendered contents of this node (e.g. JSX).
`textValue`	`string`	A string value for this node, used for features like typeahead.
`aria-label`	`string`	An accessibility label for this node.
`index`	`number`	The index of this node within its parent.
`wrapper`	`( (element: ReactElement )) => ReactElement`	A function that should be called to wrap the rendered node.
`parentKey`	`Key \| null`	The key of the parent node.
`prevKey`	`Key \| null`	The key of the node before this node.
`nextKey`	`Key \| null`	The key of the node after this node.
`props`	`any`	Additional properties specific to a particular node type.
`render`	`( (node: Node<any> )) => ReactElement`	A function that renders this node to a React Element in the DOM.

string | number

An interface for reading and updating multiple selection state.

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.
`selectedKeys`	`Set<Key>`	The currently selected keys in the collection.
`rawSelection`	`Selection`	The raw selection value for the collection. Either 'all' for select all, or a set of keys.
`isEmpty`	`boolean`	Whether the selection is empty.
`isSelectAll`	`boolean`	Whether all items in the collection are selected.
`firstSelectedKey`	`Key \| null`
`lastSelectedKey`	`Key \| null`
`disabledKeys`	`Set<Key>`
`disabledBehavior`	`DisabledBehavior`

Methods

Method	Description
`constructor( collection: Collection<Node<unknown>>, state: MultipleSelectionState, options?: SelectionManagerOptions ): void`
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , childFocusStrategy?: FocusStrategy )): void`	Sets the focused key.
`isSelected( (key: Key )): void`	Returns whether a key is selected.
`extendSelection( (toKey: Key )): void`	Extends the selection to the given key.
`toggleSelection( (key: Key )): void`	Toggles whether the given key is selected.
`replaceSelection( (key: Key )): void`	Replaces the selection with only the given key.
`setSelectedKeys( (keys: Iterable<Key> )): void`	Replaces the selection with the given keys.
`selectAll(): void`	Selects all items in the collection.
`clearSelection(): void`	Removes all keys from the selection.
`toggleSelectAll(): void`	Toggles between select all and an empty selection.
`select( (key: Key, , e?: PressEvent \| LongPressEvent \| PointerEvent )): void`
`isSelectionEqual( (selection: Set<Key> )): void`	Returns whether the current selection is equal to the given selection.
`canSelectItem( (key: Key )): void`
`isDisabled( (key: Key )): void`
`isLink( (key: Key )): void`
`getItemProps( (key: Key )): void`

Properties

Name	Type	Description
`selectionMode`	`SelectionMode`	The type of selection that is allowed in the collection.
`selectionBehavior`	`SelectionBehavior`	The selection behavior for the collection.
`disallowEmptySelection`	`boolean`	Whether the collection allows empty selection.
`selectedKeys`	`Selection`	The currently selected keys in the collection.
`disabledKeys`	`Set<Key>`	The currently disabled keys in the collection.
`disabledBehavior`	`DisabledBehavior`	Whether `disabledKeys` applies to selection, actions, or both.
`isFocused`	`boolean`	Whether the collection is currently focused.
`focusedKey`	`Key`	The current focused key in the collection.
`childFocusStrategy`	`FocusStrategy`	Whether the first or last child of the focused key should receive focus.

Methods

Method	Description
`setSelectionBehavior( (selectionBehavior: SelectionBehavior )): void`	Sets the selection behavior for the collection.
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys in the collection.
`setFocused( (isFocused: boolean )): void`	Sets whether the collection is focused.
`setFocusedKey( (key: Key \| \| null, , child?: FocusStrategy )): void`	Sets the focused key, and optionally, whether the first or last child of that key should receive focus.

'none'
  | 'single'
  | 'multiple'

'toggle' | 'replace'

'all' | Set<Key>

'selection' | 'all'

'first' | 'last'

A LayoutDelegate provides layout information for collection items.

Method	Description
`getItemRect( (key: Key )): Rect \| null`	Returns a rectangle for the item with the given key.
`getVisibleRect(): Rect`	Returns the visible rectangle of the collection.
`getContentSize(): Size`	Returns the size of the scrollable content in the collection.
`getKeyRange( (from: Key, , to: Key )): Key[]`	Returns a list of keys between `from` and `to`.

Name	Type	Description
`x`	`number`
`y`	`number`
`width`	`number`
`height`	`number`

Name	Type	Description
`width`	`number`
`height`	`number`

Name	Type	Description
`allowsCellSelection`	`boolean`
`layoutDelegate`	`LayoutDelegate`

Properties

Name	Type	Description
`type`	`'pressstart' \| 'pressend' \| 'pressup' \| 'press'`	The type of press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Methods

Method	Description
`continuePropagation(): void`	By default, press events stop propagation to parent elements. In cases where a handler decides not to handle a specific event, it can call `continuePropagation()` to allow a parent to handle it.

'mouse'
  | 'pen'
  | 'touch'
  | 'keyboard'
  | 'virtual'

Name	Type	Description
`type`	`'longpressstart' \| 'longpressend' \| 'longpress'`	The type of long press event being fired.
`pointerType`	`PointerType`	The pointer type that triggered the press event.
`target`	`Element`	The target element of the press event.
`shiftKey`	`boolean`	Whether the shift keyboard modifier was held during the press event.
`ctrlKey`	`boolean`	Whether the ctrl keyboard modifier was held during the press event.
`metaKey`	`boolean`	Whether the meta keyboard modifier was held during the press event.
`altKey`	`boolean`	Whether the alt keyboard modifier was held during the press event.
`x`	`number`	X position relative to the target.
`y`	`number`	Y position relative to the target.

Name	Type	Description
`color`	`Color`	The color of the swatch.
`isHovered`	`boolean`	Whether the item is currently hovered with a mouse.
`isPressed`	`boolean`	Whether the item is currently in a pressed state.
`isSelected`	`boolean`	Whether the item is currently selected.
`isFocused`	`boolean`	Whether the item is currently focused.
`isFocusVisible`	`boolean`	Whether the item is currently keyboard focused.
`isDisabled`	`boolean`	Whether the item is non-interactive, i.e. both selection and actions are disabled and the item may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
`allowsDragging`	`boolean`	Whether the item allows dragging.
`isDragging`	`boolean`	Whether the item is currently being dragged.
`isDropTarget`	`boolean`	Whether the item is currently an active drop target.

Name	Type	Description
`type`	`'hoverstart' \| 'hoverend'`	The type of hover event being fired.
`pointerType`	`'mouse' \| 'pen'`	The pointer type that triggered the hover event.
`target`	`HTMLElement`	The target element of the hover event.

Name	Type	Default	Description
`children`	`ReactNode`	—	The children of the ColorSwatchPicker.
`layout`	`'grid' \| 'stack'`	`'grid'`	Whether the items are arranged in a stack or grid.
`value`	`string \| Color`	—	The current value (controlled).
`defaultValue`	`string \| Color`	—	The default value (uncontrolled).
`onChange`	`( (value: Color )) => void`	—	Handler that is called when the value changes.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.
`className`	`string \| ( (values: ColorSwatchPickerRenderProps & & {defaultClassName: string \| \| undefined } )) => string`	—	The CSS className for the element. A function may be provided to compute the class based on component state.
`style`	`CSSProperties \| ( (values: ColorSwatchPickerRenderProps & & {defaultStyle: CSSProperties } )) => CSSProperties \| undefined`	—	The inline style for the element. A function may be provided to compute the style based on component state.