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.

<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

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.

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