dotUI
dotUI
beta
  1. Components
  2. Colors
  3. Color Field

Color Field

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

<ColorField label="Color" />

Installation

Install the following dependencies:

npm install react-aria-components

Copy and paste the following code into your project.

"use client";

import * as React from "react";
import {
  ColorField as AriaColorField,
  type ColorFieldProps as AriaColorFieldProps,
} from "react-aria-components";
import { tv, type VariantProps } from "tailwind-variants";
import { Field, type FieldProps } from "./field";
import { InputRoot, Input, type inputStyles } from "./input";

const colorFieldStyles = tv({
  base: "flex flex-col gap-2 items-start w-48",
});

type ColorFieldProps = ColorFieldRootProps &
  Omit<FieldProps, "children"> &
  VariantProps<typeof inputStyles> & {
    prefix?: React.ReactNode;
    suffix?: React.ReactNode;
    isLoading?: boolean;
    loaderPosition?: "prefix" | "suffix";
    placeholder?: string;
  };
const ColorField = React.forwardRef<HTMLInputElement, ColorFieldProps>(
  (
    {
      className,
      size,
      placeholder,
      label,
      description,
      errorMessage,
      prefix,
      suffix,
      isLoading,
      loaderPosition = "suffix",
      isRequired,
      necessityIndicator,
      contextualHelp,
      ...props
    },
    ref
  ) => {
    return (
      <ColorFieldRoot className={className} isRequired={isRequired} {...props}>
        <Field
          label={label}
          description={description}
          errorMessage={errorMessage}
          isRequired={isRequired}
          necessityIndicator={necessityIndicator}
          contextualHelp={contextualHelp}
        >
          <InputRoot
            size={size}
            prefix={prefix}
            suffix={suffix}
            isLoading={isLoading}
            loaderPosition={loaderPosition}
          >
            <Input ref={ref} placeholder={placeholder} />
          </InputRoot>
        </Field>
      </ColorFieldRoot>
    );
  }
);
ColorField.displayName = "ColorField";

type ColorFieldRootProps = Omit<AriaColorFieldProps, "className"> & {
  className?: string;
};
const ColorFieldRoot = React.forwardRef<
  React.ElementRef<typeof AriaColorField>,
  ColorFieldRootProps
>(({ className, ...props }, ref) => {
  return <AriaColorField ref={ref} className={colorFieldStyles({ className })} {...props} />;
});
ColorFieldRoot.displayName = "ColorFieldRoot";

export type { ColorFieldProps, ColorFieldRootProps };
export { ColorField, ColorFieldRoot };

Update the import paths to match your project setup.

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.

Enter a background color.
<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.

Please fill out this field.
<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.

Current color value: #7F007F

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.

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

API Reference

PropTypeDefaultDescription
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.
EventTypeDescription
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 attributeDescription
[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.
dotUI
beta

Accessible, mobile friendly, modern UI components.

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