alpha

useColorSlider

Provides the behavior and accessibility implementation for a color slider component. Color sliders allow users to adjust an individual channel of a color value.

install	`yarn add @react-aria/color`
version	3.0.0-alpha.0
usage	`import {useColorSlider} from '@react-aria/color'`

View ARIA spec

API#

useColorSlider(
  (props: ColorSliderAriaOptions,
  , state: ColorSliderState
)): ColorSliderAria

Example#

import {useColorSliderState} from '@react-stately/color';
import {VisuallyHidden} from '@react-aria/visually-hidden';
import {useLocale} from '@react-aria/i18n';
import {useFocusRing} from '@react-aria/focus';

const TRACK_THICKNESS = 28;
const THUMB_SIZE = 20;

function ColorSlider(props) {
  let {locale} = useLocale();
  let state = useColorSliderState({...props, locale});
  let trackRef = React.useRef();
  let inputRef = React.useRef();

  // Default label to the channel name in the current locale
  let label = props.label || state.value.getChannelName(props.channel, locale);

  let {
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      label,
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();

  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300
      }}>
      {/* Create a flex container for the label and output element. */}
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        <label {...labelProps}>{label}</label>
        <output {...outputProps} style={{flex: '1 0 auto', textAlign: 'end'}}>
          {state.value.formatChannelValue(props.channel, locale)}
        </output>
      </div>
      {/* The track element holds the visible track line and the thumb. */}
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          height: TRACK_THICKNESS,
          width: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            top: TRACK_THICKNESS / 2,
            border: '2px solid white',
            boxShadow: '0 0 0 1px black, inset 0 0 0 1px black',
            width: isFocusVisible ? TRACK_THICKNESS + 4 : THUMB_SIZE,
            height: isFocusVisible ? TRACK_THICKNESS + 4 : THUMB_SIZE,
            borderRadius: '50%',
            boxSizing: 'border-box',
            background: state.getDisplayColor().toString('css')
          }}>
          <VisuallyHidden>
            <input ref={inputRef} {...inputProps} {...focusProps} />
          </VisuallyHidden>
        </div>
      </div>
    </div>
  );
}

<ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" />

import {useColorSliderState} from '@react-stately/color';
import {VisuallyHidden} from '@react-aria/visually-hidden';
import {useLocale} from '@react-aria/i18n';
import {useFocusRing} from '@react-aria/focus';

const TRACK_THICKNESS = 28;
const THUMB_SIZE = 20;

function ColorSlider(props) {
  let {locale} = useLocale();
  let state = useColorSliderState({...props, locale});
  let trackRef = React.useRef();
  let inputRef = React.useRef();

  // Default label to the channel name in the current locale
  let label =
    props.label ||
    state.value.getChannelName(props.channel, locale);

  let {
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      label,
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();

  return (
    <div
      style={{
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300
      }}>
      {/* Create a flex container for the label and output element. */}
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        <label {...labelProps}>{label}</label>
        <output
          {...outputProps}
          style={{flex: '1 0 auto', textAlign: 'end'}}>
          {state.value.formatChannelValue(
            props.channel,
            locale
          )}
        </output>
      </div>
      {/* The track element holds the visible track line and the thumb. */}
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          height: TRACK_THICKNESS,
          width: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            top: TRACK_THICKNESS / 2,
            border: '2px solid white',
            boxShadow:
              '0 0 0 1px black, inset 0 0 0 1px black',
            width: isFocusVisible
              ? TRACK_THICKNESS + 4
              : THUMB_SIZE,
            height: isFocusVisible
              ? TRACK_THICKNESS + 4
              : THUMB_SIZE,
            borderRadius: '50%',
            boxSizing: 'border-box',
            background: state
              .getDisplayColor()
              .toString('css')
          }}>
          <VisuallyHidden>
            <input
              ref={inputRef}
              {...inputProps}
              {...focusProps}
            />
          </VisuallyHidden>
        </div>
      </div>
    </div>
  );
}

<ColorSlider
  channel="hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

import {useColorSliderState} from '@react-stately/color';
import {VisuallyHidden} from '@react-aria/visually-hidden';
import {useLocale} from '@react-aria/i18n';
import {useFocusRing} from '@react-aria/focus';

const TRACK_THICKNESS = 28;
const THUMB_SIZE = 20;

function ColorSlider(
  props
) {
  let {
    locale
  } = useLocale();
  let state = useColorSliderState(
    {...props, locale}
  );
  let trackRef = React.useRef();
  let inputRef = React.useRef();

  // Default label to the channel name in the current locale
  let label =
    props.label ||
    state.value.getChannelName(
      props.channel,
      locale
    );

  let {
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      label,
      trackRef,
      inputRef
    },
    state
  );

  let {
    focusProps,
    isFocusVisible
  } = useFocusRing();

  return (
    <div
      style={{
        display: 'flex',
        flexDirection:
          'column',
        alignItems:
          'center',
        width: 300
      }}>
      {/* Create a flex container for the label and output element. */}
      <div
        style={{
          display:
            'flex',
          alignSelf:
            'stretch'
        }}>
        <label
          {...labelProps}>
          {label}
        </label>
        <output
          {...outputProps}
          style={{
            flex:
              '1 0 auto',
            textAlign:
              'end'
          }}>
          {state.value.formatChannelValue(
            props.channel,
            locale
          )}
        </output>
      </div>
      {/* The track element holds the visible track line and the thumb. */}
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          height: TRACK_THICKNESS,
          width: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            top:
              TRACK_THICKNESS /
              2,
            border:
              '2px solid white',
            boxShadow:
              '0 0 0 1px black, inset 0 0 0 1px black',
            width: isFocusVisible
              ? TRACK_THICKNESS +
                4
              : THUMB_SIZE,
            height: isFocusVisible
              ? TRACK_THICKNESS +
                4
              : THUMB_SIZE,
            borderRadius:
              '50%',
            boxSizing:
              'border-box',
            background: state
              .getDisplayColor()
              .toString(
                'css'
              )
          }}>
          <VisuallyHidden>
            <input
              ref={
                inputRef
              }
              {...inputProps}
              {...focusProps}
            />
          </VisuallyHidden>
        </div>
      </div>
    </div>
  );
}

<ColorSlider
  channel="hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

Vertical#

function ColorSlider(props) {
  let {locale} = useLocale();
  let state = useColorSliderState({...props, locale});
  let trackRef = React.useRef();
  let inputRef = React.useRef();
  let {
    groupProps,
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      orientation: 'vertical',
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();

  return (
    <div
      {...groupProps}
      style={{
        height: 200
      }}>
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          width: TRACK_THICKNESS,
          height: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            left: TRACK_THICKNESS / 2,
            border: '2px solid white',
            boxShadow: '0 0 0 1px black, inset 0 0 0 1px black',
            width: isFocusVisible ? TRACK_THICKNESS + 4 : THUMB_SIZE,
            height: isFocusVisible ? TRACK_THICKNESS + 4 : THUMB_SIZE,
            borderRadius: '50%',
            boxSizing: 'border-box',
            background: state.getDisplayColor().toString('css')
          }}>
          <VisuallyHidden>
            <input ref={inputRef} {...inputProps} {...focusProps} />
          </VisuallyHidden>
        </div>
      </div>
    </div>
  );
}

<ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" />

function ColorSlider(props) {
  let {locale} = useLocale();
  let state = useColorSliderState({...props, locale});
  let trackRef = React.useRef();
  let inputRef = React.useRef();
  let {
    groupProps,
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      orientation: 'vertical',
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();

  return (
    <div
      {...groupProps}
      style={{
        height: 200
      }}>
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          width: TRACK_THICKNESS,
          height: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            left: TRACK_THICKNESS / 2,
            border: '2px solid white',
            boxShadow:
              '0 0 0 1px black, inset 0 0 0 1px black',
            width: isFocusVisible
              ? TRACK_THICKNESS + 4
              : THUMB_SIZE,
            height: isFocusVisible
              ? TRACK_THICKNESS + 4
              : THUMB_SIZE,
            borderRadius: '50%',
            boxSizing: 'border-box',
            background: state
              .getDisplayColor()
              .toString('css')
          }}>
          <VisuallyHidden>
            <input
              ref={inputRef}
              {...inputProps}
              {...focusProps}
            />
          </VisuallyHidden>
        </div>
      </div>
    </div>
  );
}

<ColorSlider
  channel="hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

function ColorSlider(
  props
) {
  let {
    locale
  } = useLocale();
  let state = useColorSliderState(
    {...props, locale}
  );
  let trackRef = React.useRef();
  let inputRef = React.useRef();
  let {
    groupProps,
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      orientation:
        'vertical',
      trackRef,
      inputRef
    },
    state
  );

  let {
    focusProps,
    isFocusVisible
  } = useFocusRing();

  return (
    <div
      {...groupProps}
      style={{
        height: 200
      }}>
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          width: TRACK_THICKNESS,
          height: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            left:
              TRACK_THICKNESS /
              2,
            border:
              '2px solid white',
            boxShadow:
              '0 0 0 1px black, inset 0 0 0 1px black',
            width: isFocusVisible
              ? TRACK_THICKNESS +
                4
              : THUMB_SIZE,
            height: isFocusVisible
              ? TRACK_THICKNESS +
                4
              : THUMB_SIZE,
            borderRadius:
              '50%',
            boxSizing:
              'border-box',
            background: state
              .getDisplayColor()
              .toString(
                'css'
              )
          }}>
          <VisuallyHidden>
            <input
              ref={
                inputRef
              }
              {...inputProps}
              {...focusProps}
            />
          </VisuallyHidden>
        </div>
      </div>
    </div>
  );
}

<ColorSlider
  channel="hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

Usage#

RGBA#

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

function Example() {
  let [color, setColor] = React.useState(parseColor('#7f007f'));
  return (
    <>
      <ColorSlider channel="red" value={color} onChange={setColor} />
      <ColorSlider channel="green" value={color} onChange={setColor} />
      <ColorSlider channel="blue" value={color} onChange={setColor} />
      <ColorSlider channel="alpha" value={color} onChange={setColor} />
    </>
  );
}

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

function Example() {
  let [color, setColor] = React.useState(
    parseColor('#7f007f')
  );
  return (
    <>
      <ColorSlider
        channel="red"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="green"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="blue"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="alpha"
        value={color}
        onChange={setColor}
      />
    </>
  );
}

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

function Example() {
  let [
    color,
    setColor
  ] = React.useState(
    parseColor('#7f007f')
  );
  return (
    <>
      <ColorSlider
        channel="red"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="green"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="blue"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="alpha"
        value={color}
        onChange={
          setColor
        }
      />
    </>
  );
}

HSLA#

function Example() {
  let [color, setColor] = React.useState(parseColor('hsl(0, 100%, 50%)'));
  return (
    <>
      <ColorSlider channel="hue" value={color} onChange={setColor} />
      <ColorSlider channel="saturation" value={color} onChange={setColor} />
      <ColorSlider channel="lightness" value={color} onChange={setColor} />
      <ColorSlider channel="alpha" value={color} onChange={setColor} />
    </>
  );
}

function Example() {
  let [color, setColor] = React.useState(
    parseColor('hsl(0, 100%, 50%)')
  );
  return (
    <>
      <ColorSlider
        channel="hue"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="saturation"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="lightness"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="alpha"
        value={color}
        onChange={setColor}
      />
    </>
  );
}

function Example() {
  let [
    color,
    setColor
  ] = React.useState(
    parseColor(
      'hsl(0, 100%, 50%)'
    )
  );
  return (
    <>
      <ColorSlider
        channel="hue"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="saturation"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="lightness"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="alpha"
        value={color}
        onChange={
          setColor
        }
      />
    </>
  );
}

HSBA#

function Example() {
  let [color, setColor] = React.useState(parseColor('hsb(0, 100%, 50%)'));
  return (
    <>
      <ColorSlider channel="hue" value={color} onChange={setColor} />
      <ColorSlider channel="saturation" value={color} onChange={setColor} />
      <ColorSlider channel="brightness" value={color} onChange={setColor} />
      <ColorSlider channel="alpha" value={color} onChange={setColor} />
    </>
  );
}

function Example() {
  let [color, setColor] = React.useState(
    parseColor('hsb(0, 100%, 50%)')
  );
  return (
    <>
      <ColorSlider
        channel="hue"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="saturation"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="brightness"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="alpha"
        value={color}
        onChange={setColor}
      />
    </>
  );
}

function Example() {
  let [
    color,
    setColor
  ] = React.useState(
    parseColor(
      'hsb(0, 100%, 50%)'
    )
  );
  return (
    <>
      <ColorSlider
        channel="hue"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="saturation"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="brightness"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="alpha"
        value={color}
        onChange={
          setColor
        }
      />
    </>
  );
}

Name	Type	Default	Description
`trackRef`	`RefObject<HTMLElement>`	—	A ref for the track element.
`inputRef`	`RefObject<HTMLInputElement>`	—	A ref for the input element.
`channel`	`ColorChannel`	—	The color channel that the slider manipulates.
`onChange`	`( (value: Color )) => void`	—	Handler that is called when the value changes, as the user drags.
`onChangeEnd`	`( (value: Color )) => void`	—	Handler that is called when the user stops dragging.
`showValueLabel`	`boolean`	—	Whether the value label is displayed. True by default if there is a label, false by default if not.
`orientation`	`Orientation`	`'horizontal'`	The orientation of the Slider.
`isDisabled`	`boolean`	—	Whether the whole Slider is disabled.
`step`	`number`	`1`	The slider's step value.
`value`	`string \| Color`	—	The current value (controlled).
`defaultValue`	`string \| Color`	—	The default value (uncontrolled).
`label`	`ReactNode`	—	The content to display as the label.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

A list of color channels.

'hue'
  | 'saturation'
  | 'brightness'
  | 'lightness'
  | 'red'
  | 'green'
  | 'blue'
  | 'alpha'

Represents a color value.

Method	Description
`toFormat( (format: ColorFormat )): Color`	Converts the color to the given color format, and returns a new Color object.
`toHexInt(): number`	Converts the color to hex, and returns an integer representation.
`getChannelValue( (channel: ColorChannel )): number`	Returns the numeric value for a given channel. Throws an error if the channel is unsupported in the current color format.
`withChannelValue( (channel: ColorChannel, , value: number )): Color`	Sets the numeric value for a given channel, and returns a new Color object. Throws an error if the channel is unsupported in the current color format.
`getChannelRange( (channel: ColorChannel )): ColorChannelRange`	Returns the minimum, maximum, and step values for a given channel.
`getChannelName( (channel: ColorChannel, , locale: string )): string`	Returns a localized color channel name for a given channel and locale, for use in visual or accessibility labels.
`formatChannelValue( (channel: ColorChannel, , locale: string )): string`	Formats the numeric value for a given channel for display according to the provided locale.

A list of supported color formats.

'hex'
  | 'hexa'
  | 'rgb'
  | 'rgba'
  | 'hsl'
  | 'hsla'
  | 'hsb'
  | 'hsba'

Name	Type	Description
`minValue`	`number`	The minimum value of the color channel.
`maxValue`	`number`	The maximum value of the color channel.
`step`	`number`	The step value of the color channel, used when incrementing and decrementing.

'horizontal' | 'vertical'

Properties

Name	Type	Description
`value`	`Color`	The current color value represented by the color slider.
`values`	`number[]`	Values managed by the slider by thumb index.
`focusedThumb`	`number \| undefined`	Currently-focused thumb index.
`step`	`number`	The step amount for the slider.

Methods

Method	Description
`setValue( (value: string \| \| Color )): void`	Sets the current color value. If a string is passed, it will be parsed to a Color.
`getDisplayColor(): Color`	Returns the color that should be displayed in the slider instead of `value` or the optional parameter.
`getThumbValue( (index: number )): number`	Get the value for the specified thumb.
`setThumbValue( (index: number, , value: number )): void`	Sets the value for the specified thumb. The actual value set will be clamped and rounded according to min/max/step.
`setThumbPercent( (index: number, , percent: number )): void`	Sets value for the specified thumb by percent offset (between 0 and 1).
`isThumbDragging( (index: number )): boolean`	Whether the specific thumb is being dragged.
`setThumbDragging( (index: number, , dragging: boolean )): void`	Set is dragging on the specified thumb.
`setFocusedThumb( (index: number \| \| undefined )): void`	Set focused true on specified thumb. This will remove focus from any thumb that had it before.
`getThumbPercent( (index: number )): number`	Returns the specified thumb's value as a percentage from 0 to 1.
`getValuePercent( (value: number )): number`	Returns the value as a percent between the min and max of the slider.
`getThumbValueLabel( (index: number )): string`	Returns the string label for the specified thumb's value, per props.formatOptions.
`getFormattedValue( (value: number )): string`	Returns the string label for the value, per props.formatOptions.
`getThumbMinValue( (index: number )): number`	Returns the min allowed value for the specified thumb.
`getThumbMaxValue( (index: number )): number`	Returns the max allowed value for the specified thumb.
`getPercentValue( (percent: number )): number`	Converts a percent along track (between 0 and 1) to the corresponding value.
`isThumbEditable( (index: number )): boolean`	Returns if the specified thumb is editable.
`setThumbEditable( (index: number, , editable: boolean )): void`	Set the specified thumb's editable state.

Name	Type	Description
`labelProps`	`HTMLAttributes<HTMLElement>`	Props for the label element.
`trackProps`	`HTMLAttributes<HTMLElement>`	Props for the track element.
`thumbProps`	`HTMLAttributes<HTMLElement>`	Props for the thumb element.
`inputProps`	`HTMLAttributes<HTMLElement>`	Props for the visually hidden range input element.
`outputProps`	`HTMLAttributes<HTMLElement>`	Props for the output element, displaying the value of the color slider.