Components
Colors
Color Field

Color Field

A color field allows users to edit a hex color or individual color channel value.

Aria docs Report an issue Edit this page

Color

default.tsx

<ColorField label="Color" />

Installation

npm

pnpm

yarn

bun

npx dotui-cli@latest add color-field

Anatomy

import { ColorField } from "@/components/core/color-field";
 
<ColorField label="Background" description="Enter a background color." />;

import { ColorFieldRoot, ColorFiedInput } from "@/components/core/color-field";
import { Label, Description, FieldError } from "@/components/core/field";
 
<ColorFieldRoot>
  <Label>Background</Label>
  <ColorFieldInput />
  <Description>Enter a background color.</Description>
  <FieldError />
</ColorFieldRoot>;

Controlled

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

Color

Current color value: #7F007F

controlled.tsx

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

Color channel

By default, ColorField allows the user to edit the color as a hex value. When the colorSpace and channel props are provided, ColorField displays the value for that channel formatted as a number instead.Rendering multiple ColorFields together can allow a user to edit a color.

Hue

Saturation

Lightness

color-channel.tsx

<ColorField label="Hue" colorSpace="hsl" channel="hue" />
<ColorField label="Saturation" colorSpace="hsl" channel="saturation" />
<ColorField label="Lightness" colorSpace="hsl" channel="lightness" />

Label

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

Background

label.tsx

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

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.

Color

Enter a background color.

description.tsx

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

Validation

By default, ColorField displays default validation messages provided by the browser. You can customize this using the errorMessage prop, which will be displayed when the isInvalid prop is set to true.

Color

Please fill out this field.

error-message.tsx

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

Options

Size

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

small

medium

large

sizes.tsx

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

prefix-and-suffix.tsx

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

Disabled

Use the isDisabled prop to disable the ColorField.

disabled.tsx

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

Color

read-only.tsx

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

Color

required.tsx

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

Composition

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

Background

Enter a background color.

composition.tsx

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

API Reference

Prop	Type	Default	Description
`channel`	`'hue' \| 'saturation' \| 'brightness' \| 'lightness' \| 'red' \| 'green' \| 'blue' \| 'alpha'`	-	The color channel that this field edits. If not provided, the color is edited as a hex value.
`colorSpace`	`'rgb' \| 'hsl' \| 'hsb'`	-	The color space that the color field operates in if a channel prop is provided. If no channel is provided, the color field always displays the color as an RGB hex value.
`isWheelDisabled`	`boolean`	-	Enables or disables changing the value with scroll.
`value`	`T`	-	The current value (controlled).
`defaultValue`	`T`	-	The default value (uncontrolled).
`isDisabled`	`boolean`	-	Whether the input is disabled.
`isReadOnly`	`boolean`	-	Whether the input can be selected but not changed by the user.
`isRequired`	`boolean`	-	Whether user input is required on the input before form submission.
`isInvalid`	`boolean`	-	Whether the input value is invalid.
`validate`	`(value: Color \| null) => ValidationError \| true \| null \| undefined`	-	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.
`autoFocus`	`boolean`	-	Whether the element should receive focus on render.
`name`	`string`	-	The name of the input element, used when submitting an HTML form.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.
`children`	`ReactNode \| (values: ColorFieldRenderProps & {defaultChildren: ReactNode \| undefined}) => ReactNode`	-	The children of the component. A function may be provided to alter the children based on component state.
`className`	`string`	-	The CSS className for the element.
`style`	`CSSProperties \| (values: ColorFieldRenderProps & {defaultStyle: CSSProperties}) => CSSProperties`	-	The inline style for the element. A function may be provided to compute the style based on component state.

Event	Type	Description
`onChange`	`(isSelected: boolean) => void`	Handler that is called when the Switch's selection state changes.
`onFocus`	`(e: FocusEvent<Target>) => void`	Handler that is called when the Switch receives focus.
`onBlur`	`(e: FocusEvent<Target>) => void`	Handler that is called when the Switch loses focus.
`onFocusChange`	`(isFocused: boolean) => void`	Handler that is called when the Switch's focus status changes.
`onKeyDown`	`(e: KeyboardEvent) => void`	Handler that is called when a key is pressed.
`onKeyUp`	`(e: KeyboardEvent) => void`	Handler that is called when a key is released.
`onCopy`	`ClipboardEventHandler<HTMLInputElement>`	Handler that is called when the user copies text.
`onCut`	`ClipboardEventHandler<HTMLInputElement>`	Handler that is called when the user cuts text.
`onPaste`	`ClipboardEventHandler<HTMLInputElement>`	Handler that is called when the user pastes text.
`onCompositionStart`	`CompositionEventHandler<HTMLInputElement>`	Handler that is called when a text composition system starts a new text composition session.
`onCompositionEnd`	`CompositionEventHandler<HTMLInputElement>`	Handler that is called when a text composition system completes or cancels the current text composition session.
`onCompositionUpdate`	`CompositionEventHandler<HTMLInputElement>`	Handler that is called when a new character is received in the current text composition session.
`onSelect`	`ReactEventHandler<HTMLInputElement>`	Handler that is called when text in the input is selected.
`onBeforeInput`	`FormEventHandler<HTMLInputElement>`	Handler that is called when the input value is about to be modified.
`onInput`	`FormEventHandler<HTMLInputElement>`	Handler that is called when the input value is modified.

Data attribute	Description
`[data-disabled]`	Whether the color field is disabled.
`[data-invalid]`	Whether the color field is invalid.
`[data-channel="hex \| hue \| saturation \| ..."]`	The color channel that this field edits, or "hex" if no channel prop is set.

Last updated on 10/11/2024

Color Area Color Slider

Installation Anatomy Controlled Color channel Label Description Validation Options Size Prefix and suffix Disabled ReadOnly Required Composition API Reference

dotUI

Bringing singularity to the web.

Product

Community

Support

Built by mehdibha. The source code is available on GitHub.

Buttons

Forms and inputs

Menus and selection

Date and time

Colors

Drag and drop

Feedback

Data display

Navigation

Overlays

Color Field

Installation

Anatomy

Controlled

Color channel

Label

Description

Validation

Options

Size

Prefix and suffix

Disabled

ReadOnly

Required

Composition

API Reference

Product

Community

Support