ColorWheel

ColorWheels allow users to adjust the hue of an HSL or HSB color value on a circular track.

Example#

<ColorWheel defaultValue="hsl(30, 100%, 50%)" />

<ColorWheel defaultValue="hsl(30, 100%, 50%)" />

<ColorWheel defaultValue="hsl(30, 100%, 50%)" />

Value#

A ColorWheel's value specifies the position of the ColorWheel's thumb on the track, and accepts a string or Color object. It is initialized as hsl(0, 100%, 50%) by default, but an alternative initial uncontrolled value can be provided using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop. Note that only HSB(A) values are supported as valid values.

In the example below, the parseColor function is used to parse the initial color from a HSL string so that value's type remains consistent.

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

function Example() {
  let [value, setValue] = React.useState(parseColor('hsl(30, 100%, 50%)'));
  return (
    <Flex gap="size-300" wrap>
      <Flex direction="column" alignItems="center">
        <label id="label-1">Hue (uncontrolled)</label>
        <ColorWheel
          defaultValue="hsl(30, 100%, 50%)"
          aria-labelledby="label-1"
        />
      </Flex>
      <Flex direction="column" alignItems="center">
        <label id="label-2">Hue (controlled)</label>
        <ColorWheel
          value={value}
          onChange={setValue}
          aria-labelledby="label-1"
        />
      </Flex>
    </Flex>
  );
}

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

function Example() {
  let [value, setValue] = React.useState(
    parseColor('hsl(30, 100%, 50%)')
  );
  return (
    <Flex gap="size-300" wrap>
      <Flex direction="column" alignItems="center">
        <label id="label-1">Hue (uncontrolled)</label>
        <ColorWheel
          defaultValue="hsl(30, 100%, 50%)"
          aria-labelledby="label-1"
        />
      </Flex>
      <Flex direction="column" alignItems="center">
        <label id="label-2">Hue (controlled)</label>
        <ColorWheel
          value={value}
          onChange={setValue}
          aria-labelledby="label-1"
        />
      </Flex>
    </Flex>
  );
}

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

function Example() {
  let [
    value,
    setValue
  ] = React.useState(
    parseColor(
      'hsl(30, 100%, 50%)'
    )
  );
  return (
    <Flex
      gap="size-300"
      wrap>
      <Flex
        direction="column"
        alignItems="center">
        <label id="label-1">
          Hue
          (uncontrolled)
        </label>
        <ColorWheel
          defaultValue="hsl(30, 100%, 50%)"
          aria-labelledby="label-1"
        />
      </Flex>
      <Flex
        direction="column"
        alignItems="center">
        <label id="label-2">
          Hue
          (controlled)
        </label>
        <ColorWheel
          value={value}
          onChange={
            setValue
          }
          aria-labelledby="label-1"
        />
      </Flex>
    </Flex>
  );
}

Labeling#

By default, a localized string for the "hue" channel name is used as the aria-label for the ColorWheel. When a custom aria-label or aria-labelledby is provided, it should be localized accordingly.

Step values#

The step prop can be used to snap the ColorWheel's value to specific increments. The value provided should the number of degrees that each step should span, ranging from 0 to 360. Note that the steps are calculated starting from 0˚ and that the final step will always snap back to 0˚, regardless of how much remaining track distance there is from the step prior.

<ColorWheel step={60} />

<ColorWheel step={60} />

<ColorWheel
  step={60}
/>

Events#

ColorWheel supports two events: onChange and onChangeEnd. onChange is triggered whenever the ColorWheel's handle is dragged, and onChangeEnd is triggered when the user stops dragging the handle. Both events receive a Color object as a parameter.

The example below uses onChange and onChangeEnd to update two separate elements with the ColorWheel's value.

function Example() {
  let [currentValue, setCurrentValue] = React.useState(
    parseColor('hsl(50, 100%, 50%)')
  );
  let [finalValue, setFinalValue] = React.useState(
    parseColor('hsl(50, 100%, 50%)')
  );

  return (
    <div>
      <ColorWheel
        value={currentValue}
        onChange={setCurrentValue}
        onChangeEnd={setFinalValue}
      />
      <pre>Current value: {currentValue.toString('hsl')}</pre>
      <pre>Final value: {finalValue.toString('hsl')}</pre>
    </div>
  );
}

function Example() {
  let [currentValue, setCurrentValue] = React.useState(
    parseColor('hsl(50, 100%, 50%)')
  );
  let [finalValue, setFinalValue] = React.useState(
    parseColor('hsl(50, 100%, 50%)')
  );

  return (
    <div>
      <ColorWheel
        value={currentValue}
        onChange={setCurrentValue}
        onChangeEnd={setFinalValue}
      />
      <pre>
        Current value: {currentValue.toString('hsl')}
      </pre>
      <pre>Final value: {finalValue.toString('hsl')}</pre>
    </div>
  );
}

function Example() {
  let [
    currentValue,
    setCurrentValue
  ] = React.useState(
    parseColor(
      'hsl(50, 100%, 50%)'
    )
  );
  let [
    finalValue,
    setFinalValue
  ] = React.useState(
    parseColor(
      'hsl(50, 100%, 50%)'
    )
  );

  return (
    <div>
      <ColorWheel
        value={
          currentValue
        }
        onChange={
          setCurrentValue
        }
        onChangeEnd={
          setFinalValue
        }
      />
      <pre>
        Current value:{' '}
        {currentValue.toString(
          'hsl'
        )}
      </pre>
      <pre>
        Final value:{' '}
        {finalValue.toString(
          'hsl'
        )}
      </pre>
    </div>
  );
}

Props#

Visual options#

Disabled#

View guidelines

<ColorWheel isDisabled />

<ColorWheel isDisabled />

<ColorWheel
  isDisabled
/>

Size#

View guidelines

<ColorWheel size="size-1600" />

<ColorWheel size="size-1600" />

<ColorWheel size="size-1600" />