Color Field

<ColorField label="Color" />

Installation

npx dotui-cli@latest add color-field

Usage

Use a ColorField to allow users to edit a hex color or individual color channel value.

Options

Label

A visual label can be provided for the ColorField using the label prop or a hidden label using aria-label prop.

<ColorField label="Background" placeholder="Visible label" />
<ColorField aria-label="Background" placeholder="Hidden label" />

Size

Use the size prop to control the size of the ColorField.
The default variant is "md".

<ColorField label="small" size="sm" />
<ColorField label="medium" size="md" />
<ColorField label="large" size="lg" />

Prefix and suffix

To add additional context for the ColorField, use the prefix and suffix props.

<ColorField prefix={<PaletteIcon />} />
<ColorField suffix={<PaletteIcon />} />

Description

A description can be supplied to ColorField via the description prop. The description is always visible unless the isInvalid prop is true and an error message is provided.

<ColorField label="Color" description="Enter a background color." />

Contextual help

A ContextualHelp element may be placed next to the label to provide additional information or help about a ColorField.

<ColorField label="Color" contextualHelp={<ContextualHelp />} />

Error message

An errorMessage can be supplied to ColorField, which will be displayed when the isInvalid prop is set to true.

<ColorField label="Color" isInvalid errorMessage="Please fill out this field." />

Loading

Use the isLoading prop to control the loading state of the ColorField. Use the loaderPosition prop to control the position of the loader.

<ColorField isLoading loaderPosition="prefix" />
<ColorField isLoading loaderPosition="suffix" />

Disabled

Use the isDisabled prop to disable the ColorField.

<ColorField value={parseColor("rgb(222,70,58)")} isDisabled />

ReadOnly

The isReadOnly boolean prop makes the ColorField's text content immutable. Unlike isDisabled, the ColorField remains focusable and the contents can still be copied.

<ColorField label="Color" isReadOnly value="#121212" />

Required

Use the isRequired prop to mark the ColorField as required. Use the necessityIndicator prop to control the visual style of the required state.

<ColorField label="Color" isRequired />
<ColorField label="Color" isRequired necessityIndicator="icon" />
<ColorField label="Color" isRequired necessityIndicator="label" />
<ColorField label="Color" necessityIndicator="label" />

Uncontrolled

Use the value and onChange props to control the value of the input.

<ColorField defaultValue="#7f007f" />

Controlled

Use the value and onChange props to control the value of the input.

const [color, setColor] = React.useState<Color | null>(parseColor("#7f007f"));
return <ColorField value={color} onChange={setColor} />

Composition

If you need to customize things further, you can drop down to the composition level.

<ColorFieldRoot>
  <Label>Background</Label>
  <InputRoot>
    <Input />
  </InputRoot>
  <Description>Enter a background color.</Description>
  <FieldError />
</ColorFieldRoot>

API Reference