ColorSwatchPicker

A controlled swatch picker for choosing one named theme color.

Examples

Default

Office colorChoose the named theme color used for this office.

<ColorSwatchPicker
  label="Office color"
  description="Choose the named theme color used for this office."
  size="md"
  value="blue"
/>

Sizes

Office colorChoose the named theme color used for this office.

Office colorChoose the named theme color used for this office.

Office colorChoose the named theme color used for this office.

function SizesStory(args: ColorSwatchPickerProps): React.JSX.Element {
  const [value, setValue] = useState(args.value);

  return (
    <div style={{display: 'grid', gap: 16, justifyItems: 'start'}}>
      <ColorSwatchPicker
        {...args}
        onChange={setValue}
        size="sm"
        value={value}
      />
      <ColorSwatchPicker
        {...args}
        onChange={setValue}
        size="md"
        value={value}
      />
      <ColorSwatchPicker
        {...args}
        onChange={setValue}
        size="lg"
        value={value}
      />
    </div>
  );
}

<SizesStory {...args} />

Subset

Office colorChoose the named theme color used for this office.

<ColorSwatchPicker
  label="Office color"
  description="Choose the named theme color used for this office."
  size="md"
  value="green"
  colors={['red', 'orange', 'green', 'blue', 'purple']}
/>

Hover

Office colorHover a swatch to see the grow effect.

<ColorSwatchPicker
  label="Office color"
  description="Hover a swatch to see the grow effect."
  size="md"
  value="purple"
/>

Disabled

Office colorChoose the named theme color used for this office.

<ColorSwatchPicker
  label="Office color"
  description="Choose the named theme color used for this office."
  size="md"
  value="blue"
  isDisabled
/>

Error

Office colorChoose the named theme color used for this office.

Choose an office color.

<ColorSwatchPicker
  label="Office color"
  description="Choose the named theme color used for this office."
  size="md"
  value="blue"
  status={{message: 'Choose an office color.', type: 'error'}}
/>

Required

Office color · RequiredChoose the named theme color used for this office.

<ColorSwatchPicker
  label="Office color"
  description="Choose the named theme color used for this office."
  size="md"
  value="blue"
  isRequired
/>

Drives Other Components

Office colorChoose the named theme color used for this office.

North officeNorth office

function DrivesOtherComponentsStory(
  args: ColorSwatchPickerProps,
): React.JSX.Element {
  const [value, setValue] = useState<ColorName>(args.value);

  return (
    <div style={{display: 'grid', gap: 16, justifyItems: 'start'}}>
      <ColorSwatchPicker {...args} onChange={setValue} value={value} />
      <div style={{display: 'flex', gap: 8}}>
        <Tag color={value} label="North office" />
        <Badge color={value} label="North office" />
      </div>
    </div>
  );
}

<DrivesOtherComponentsStory {...args} />

Read Only

Office colorChoose the named theme color used for this office.

<ColorSwatchPicker
  label="Office color"
  description="Choose the named theme color used for this office."
  size="md"
  value="blue"
  isReadOnly
/>

API

ColorSwatchPicker

A controlled swatch picker for choosing one named theme color.

When isOptional: false, isRequired: false

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the field root.
colors	ReadonlyArray<ColorName>	COLOR_NAMES	Palette colors to render, in display order.
data-testid	string	—	Test ID applied to the field root.
description	ReactNode	—	Supporting text displayed below the label.
isDisabled	boolean	false	Whether all swatches are disabled.
isReadOnly	boolean	false	Whether the selected color is displayed without allowing interaction.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the swatch picker.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onChange*	(value: ColorName) => void	—	Callback fired when the selected color changes.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the swatches.
status	InputStatus	—	Validation status displayed below the picker.
style	CSSProperties	—	Inline styles applied to the field root.
value*	"red" | "orange" | "yellow" | "green" | "teal" | "cyan" | "blue" | "purple" | "pink" | "gray"	—	The currently selected color.
isOptional	false	—
isRequired	false	—

When isOptional: true, isRequired: false

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the field root.
colors	ReadonlyArray<ColorName>	COLOR_NAMES	Palette colors to render, in display order.
data-testid	string	—	Test ID applied to the field root.
description	ReactNode	—	Supporting text displayed below the label.
isDisabled	boolean	false	Whether all swatches are disabled.
isReadOnly	boolean	false	Whether the selected color is displayed without allowing interaction.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the swatch picker.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onChange*	(value: ColorName) => void	—	Callback fired when the selected color changes.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the swatches.
status	InputStatus	—	Validation status displayed below the picker.
style	CSSProperties	—	Inline styles applied to the field root.
value*	"red" | "orange" | "yellow" | "green" | "teal" | "cyan" | "blue" | "purple" | "pink" | "gray"	—	The currently selected color.
isOptional*	true	—
isRequired	false	—

When isOptional: false, isRequired: true

Prop	Type	Default	Description
className	string	—	Additional CSS class names applied to the field root.
colors	ReadonlyArray<ColorName>	COLOR_NAMES	Palette colors to render, in display order.
data-testid	string	—	Test ID applied to the field root.
description	ReactNode	—	Supporting text displayed below the label.
isDisabled	boolean	false	Whether all swatches are disabled.
isReadOnly	boolean	false	Whether the selected color is displayed without allowing interaction.
isLabelHidden	boolean	false	Whether to visually hide the label.
label*	string	—	Label text for the swatch picker.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a link. It renders outside the label, so it does not focus the control or change its accessible name. It stays visible when isLabelHidden is true.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
onChange*	(value: ColorName) => void	—	Callback fired when the selected color changes.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the field root.
size	"sm" | "md" | "lg"	'md'	Size of the swatches.
status	InputStatus	—	Validation status displayed below the picker.
style	CSSProperties	—	Inline styles applied to the field root.
value*	"red" | "orange" | "yellow" | "green" | "teal" | "cyan" | "blue" | "purple" | "pink" | "gray"	—	The currently selected color.
isOptional	false	—
isRequired*	true	—