ColorPicker | Fragments

Preview

<ColorPicker
  label="Brand Color"
  defaultValue="#3b82f6"
/>

Installation

npx @usefragments/cli add colorpicker

pnpm add react-colorful

Writes src/fragments/ui/components/ColorPicker plus what it imports, the globals stylesheet, and .fragments/registry-lock.json, then prints the packages to add. No account, no key.

Your own registry: publish from Fragments Cloud and add --registry org/name. Connect a workspace.

Anatomy

ColorPicker is a compound: import the root and reach its parts through dot notation.

ColorPicker.preload

Examples

With Helper Text

Supporting line says where the colour will be used.

<ColorPicker
  label="Primary Color"
  defaultValue="#10b981"
  helperText="This color will be used for buttons and links"
/>

Controlled

The parent owns the value and sees every change.

<ControlledColorPickerDemo />

Multiple Pickers

A stacked set reads as one palette.

<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>
  <ColorPicker label="Primary" defaultValue="#3b82f6" />
  <ColorPicker label="Success" defaultValue="#22c55e" />
  <ColorPicker label="Warning" defaultValue="#f59e0b" />
  <ColorPicker label="Danger" defaultValue="#ef4444" />
</div>

Compact

showInput={false} drops the hex field, leaving a swatch row.

<div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
  <ColorPicker defaultValue="#ef4444" size="sm" showInput={false} />
  <ColorPicker defaultValue="#f59e0b" size="sm" showInput={false} />
  <ColorPicker defaultValue="#22c55e" size="sm" showInput={false} />
  <ColorPicker defaultValue="#3b82f6" size="sm" showInput={false} />
</div>

Sizes

Three swatch sizes: sm, md, lg.

<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', maxWidth: '240px' }}>
  <ColorPicker label="Small" defaultValue="#3b82f6" size="sm" />
  <ColorPicker label="Medium (default)" defaultValue="#3b82f6" size="md" />
  <ColorPicker label="Large" defaultValue="#3b82f6" size="lg" />
</div>

Error State

Red border on the hex field, and the reason below it.

<ColorPicker
  label="Brand Color"
  defaultValue="#7c3aed"
  error
  helperText="This color fails contrast against the page background"
/>

Disabled

Swatch will not open and the hex field will not accept typing.

<ColorPicker
  label="Locked Color"
  defaultValue="#64748b"
  helperText="This color cannot be changed"
  disabled
/>

API

Component props
Prop	Type	Default	Description
`label`	`string`	Not set	Label text above the picker
`value`	`string`	Not set	Controlled color value in hex format (#RRGGBB)
`defaultValue`	`string`	`#000000`	Default color for uncontrolled usage
`onChange`	`function`	Not set	Called with new color value when changed
`onValueChange`	`function`	Not set	Alias for onChange (Radix convention)
`helperText`	`string`	Not set	Helper text below the picker (preferred)
`description`	`string`	Not set	Deprecated alias for helperText
`error`	`boolean`	`false`	Show error styling
`disabled`	`boolean`	`false`	Disable the color picker
`size`	`enumsmmdlg`	`md`	Size variant
`showInput`	`boolean`	`true`	Show the hex input field

Accessibility

Label is tied to the hex input
The swatch button carries its own aria-label
The picker popup is reachable from the keyboard
Users can type a hex instead of dragging

Standards

Guidance

Use when

Theme and brand customisation
Any colour the user must pick freely
Design tool inputs

Avoid when

A fixed palette (use RadioGroup with swatches)
Showing a colour without editing it (use a tinted Badge)
Status colour that should come from a token

InputsiblingColorPicker is a specialized input for colors
RadioGroupalternativeUse RadioGroup for predefined color choices
FieldparentColorPicker uses Field internally for structure

Next steps

Accessibility contractThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.