ColorField

ColorFields allow users to enter a color in #rrggbb hexadecimal format.

Example#

<ColorField label="Primary Color" />

<ColorField label="Primary Color" />

<ColorField label="Primary Color" />

Value#

A ColorField's value is empty by default, but an initial, uncontrolled, value can be provided using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop. Valid values are hexadecimal color codes. The parseColor function is used to parse the initial color from a hex value, stored in state.

import {parseColor} from '@react-stately/color';

function Example() {
  let [value, setValue] = React.useState(parseColor('#e73623'));

  return (
    <Flex gap="size-150" wrap>
      <ColorField
        label="Primary Color (Uncontrolled)"
        defaultValue="#e21" />

      <ColorField
        label="Primary Color (Controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}

import {parseColor} from '@react-stately/color';

function Example() {
  let [value, setValue] = React.useState(
    parseColor('#e73623')
  );

  return (
    <Flex gap="size-150" wrap>
      <ColorField
        label="Primary Color (Uncontrolled)"
        defaultValue="#e21"
      />

      <ColorField
        label="Primary Color (Controlled)"
        value={value}
        onChange={setValue}
      />
    </Flex>
  );
}

import {parseColor} from '@react-stately/color';

function Example() {
  let [value, setValue] =
    React.useState(
      parseColor(
        '#e73623'
      )
    );

  return (
    <Flex
      gap="size-150"
      wrap
    >
      <ColorField
        label="Primary Color (Uncontrolled)"
        defaultValue="#e21"
      />

      <ColorField
        label="Primary Color (Controlled)"
        value={value}
        onChange={setValue}
      />
    </Flex>
  );
}

Labeling#

A visual label should be provided for the ColorField using the label prop. If the ColorField is required, the isRequired and necessityIndicator props can be used to show a required state.

<Flex gap="size-150" wrap>
  <ColorField label="Primary Color" />
  <ColorField label="Primary Color" isRequired />
  <ColorField label="Primary Color" isRequired necessityIndicator="label" />
  <ColorField label="Primary Color" necessityIndicator="label" />
</Flex>

<Flex gap="size-150" wrap>
  <ColorField label="Primary Color" />
  <ColorField label="Primary Color" isRequired />
  <ColorField
    label="Primary Color"
    isRequired
    necessityIndicator="label"
  />
  <ColorField
    label="Primary Color"
    necessityIndicator="label"
  />
</Flex>

<Flex
  gap="size-150"
  wrap
>
  <ColorField label="Primary Color" />
  <ColorField
    label="Primary Color"
    isRequired
  />
  <ColorField
    label="Primary Color"
    isRequired
    necessityIndicator="label"
  />
  <ColorField
    label="Primary Color"
    necessityIndicator="label"
  />
</Flex>

Accessibility#

If a visible label isn't specified, an aria-label must be provided to the ColorField for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization#

In order to internationalize a ColorField, a localized string should be passed to the label or aria-label prop. When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Validation#

ColorField can display a validation state to communicate to the user whether the current value is valid or invalid. Implement your own validation logic in your app and pass either "valid" or "invalid" to the ColorField via the validationState prop.

The example below illustrates how one would validate if the user has entered a red color. In it, the parseColor function is used to parse the initial color from a hexadecimal string so that value's type remains consistent.

function Example() {
  let [value, setValue] = React.useState(parseColor('#e73623'));
  let isValid = React.useMemo(() => {
    return value && value.red && value.red > value.green &&
      value.red > value.blue;
  }, [value]);

  return (
    <ColorField
      validationState={isValid ? 'valid' : 'invalid'}
      value={value}
      onChange={setValue}
      label="Red colors"
    />
  );
}

function Example() {
  let [value, setValue] = React.useState(
    parseColor('#e73623')
  );
  let isValid = React.useMemo(() => {
    return value && value.red && value.red > value.green &&
      value.red > value.blue;
  }, [value]);

  return (
    <ColorField
      validationState={isValid ? 'valid' : 'invalid'}
      value={value}
      onChange={setValue}
      label="Red colors"
    />
  );
}

function Example() {
  let [value, setValue] =
    React.useState(
      parseColor(
        '#e73623'
      )
    );
  let isValid = React
    .useMemo(() => {
      return value &&
        value.red &&
        value.red >
          value.green &&
        value.red >
          value.blue;
    }, [value]);

  return (
    <ColorField
      validationState={isValid
        ? 'valid'
        : 'invalid'}
      value={value}
      onChange={setValue}
      label="Red colors"
    />
  );
}

Props#

Visual options#

Quiet#

<ColorField label="Primary Color" isQuiet />

<ColorField label="Primary Color" isQuiet />

<ColorField
  label="Primary Color"
  isQuiet
/>

Disabled#

<ColorField label="Primary Color" isDisabled defaultValue="#e73623" />

<ColorField
  label="Primary Color"
  isDisabled
  defaultValue="#e73623"
/>

<ColorField
  label="Primary Color"
  isDisabled
  defaultValue="#e73623"
/>

Read only#

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

<ColorField label="Primary Color" isReadOnly defaultValue="#e73623" />

<ColorField
  label="Primary Color"
  isReadOnly
  defaultValue="#e73623"
/>

<ColorField
  label="Primary Color"
  isReadOnly
  defaultValue="#e73623"
/>

Label alignment and position#

View guidelines

By default, the label is positioned above the ColorField. The labelPosition prop can be used to position the label to the side. The labelAlign prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the left most edge of the ColorField and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

<ColorField label="Primary Color" labelPosition="side" labelAlign="end" />

<ColorField
  label="Primary Color"
  labelPosition="side"
  labelAlign="end"
/>

<ColorField
  label="Primary Color"
  labelPosition="side"
  labelAlign="end"
/>

Help text#

View guidelines

Both a description and an error message can be supplied to a ColorField. The description is always visible unless the validationState is “invalid” and an error message is provided. The error message can be used to help the user fix their input quickly and should be specific to the detected error. All strings should be localized.

function Example() {
  let [value, setValue] = React.useState(parseColor('#e73623'));
  let isValid = React.useMemo(() => {
    return value && value.red && value.red > value.green &&
      value.red > value.blue;
  }, [value]);

  return (
    <ColorField
      validationState={isValid ? 'valid' : 'invalid'}
      value={value}
      onChange={setValue}
      label="Red colors"
      description="Enter a red color."
      errorMessage={value === null
        ? 'Empty input not allowed.'
        : 'Not a red color.'}
    />
  );
}

function Example() {
  let [value, setValue] = React.useState(
    parseColor('#e73623')
  );
  let isValid = React.useMemo(() => {
    return value && value.red && value.red > value.green &&
      value.red > value.blue;
  }, [value]);

  return (
    <ColorField
      validationState={isValid ? 'valid' : 'invalid'}
      value={value}
      onChange={setValue}
      label="Red colors"
      description="Enter a red color."
      errorMessage={value === null
        ? 'Empty input not allowed.'
        : 'Not a red color.'}
    />
  );
}

function Example() {
  let [value, setValue] =
    React.useState(
      parseColor(
        '#e73623'
      )
    );
  let isValid = React
    .useMemo(() => {
      return value &&
        value.red &&
        value.red >
          value.green &&
        value.red >
          value.blue;
    }, [value]);

  return (
    <ColorField
      validationState={isValid
        ? 'valid'
        : 'invalid'}
      value={value}
      onChange={setValue}
      label="Red colors"
      description="Enter a red color."
      errorMessage={value ===
          null
        ? 'Empty input not allowed.'
        : 'Not a red color.'}
    />
  );
}

Custom width#

View guidelines

<ColorField label="Primary Color" width="size-3600" maxWidth="100%" />

<ColorField
  label="Primary Color"
  width="size-3600"
  maxWidth="100%"
/>

<ColorField
  label="Primary Color"
  width="size-3600"
  maxWidth="100%"
/>