alpha

useColorSlider

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

View ARIA spec

W3C

API#

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

Features#

Example#

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

const TRACK_THICKNESS = 28;
const THUMB_SIZE = 20;

function ColorSlider(props) {
  let numberFormatter = useNumberFormatter({
    style: props.channel === 'alpha' ? 'percent' : 'decimal'
  });

  let state = useColorSliderState({...props, numberFormatter});
  let trackRef = React.useRef();
  let inputRef = React.useRef();
  let {
    groupProps,
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();

  return (
    <div
      {...groupProps}
      style={{
        position: 'relative',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300,
        touchAction: 'none'
      }}>
      {/* Create a flex container for the label and output element. */}
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        {props.label && <label {...labelProps}>{props.label}</label>}
        <output {...outputProps} style={{flex: '1 0 auto', textAlign: 'end'}}>
          {state.getThumbValueLabel(0)}
        </output>
      </div>
      {/* The track element holds the visible track line and the thumb. */}
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          position: 'relative',
          height: TRACK_THICKNESS,
          width: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            position: 'absolute',
            transform: 'translate(-50%, -50%)',
            left: `${state.getThumbPercent(0) * 100}%`,
            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" label="Hue" defaultValue="hsl(0, 100%, 50%)" />

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

const TRACK_THICKNESS = 28;
const THUMB_SIZE = 20;

function ColorSlider(props) {
  let numberFormatter = useNumberFormatter({
    style: props.channel === 'alpha' ? 'percent' : 'decimal'
  });

  let state = useColorSliderState({
    ...props,
    numberFormatter
  });
  let trackRef = React.useRef();
  let inputRef = React.useRef();
  let {
    groupProps,
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      trackRef,
      inputRef
    },
    state
  );

  let {focusProps, isFocusVisible} = useFocusRing();

  return (
    <div
      {...groupProps}
      style={{
        position: 'relative',
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        width: 300,
        touchAction: 'none'
      }}>
      {/* Create a flex container for the label and output element. */}
      <div style={{display: 'flex', alignSelf: 'stretch'}}>
        {props.label && (
          <label {...labelProps}>{props.label}</label>
        )}
        <output
          {...outputProps}
          style={{flex: '1 0 auto', textAlign: 'end'}}>
          {state.getThumbValueLabel(0)}
        </output>
      </div>
      {/* The track element holds the visible track line and the thumb. */}
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          position: 'relative',
          height: TRACK_THICKNESS,
          width: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            position: 'absolute',
            transform: 'translate(-50%, -50%)',
            left: `${state.getThumbPercent(0) * 100}%`,
            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"
  label="Hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

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

const TRACK_THICKNESS = 28;
const THUMB_SIZE = 20;

function ColorSlider(
  props
) {
  let numberFormatter = useNumberFormatter(
    {
      style:
        props.channel ===
        'alpha'
          ? 'percent'
          : 'decimal'
    }
  );

  let state = useColorSliderState(
    {
      ...props,
      numberFormatter
    }
  );
  let trackRef = React.useRef();
  let inputRef = React.useRef();
  let {
    groupProps,
    trackProps,
    thumbProps,
    inputProps,
    labelProps,
    outputProps
  } = useColorSlider(
    {
      ...props,
      trackRef,
      inputRef
    },
    state
  );

  let {
    focusProps,
    isFocusVisible
  } = useFocusRing();

  return (
    <div
      {...groupProps}
      style={{
        position:
          'relative',
        display: 'flex',
        flexDirection:
          'column',
        alignItems:
          'center',
        width: 300,
        touchAction:
          'none'
      }}>
      {/* Create a flex container for the label and output element. */}
      <div
        style={{
          display:
            'flex',
          alignSelf:
            'stretch'
        }}>
        {props.label && (
          <label
            {...labelProps}>
            {props.label}
          </label>
        )}
        <output
          {...outputProps}
          style={{
            flex:
              '1 0 auto',
            textAlign:
              'end'
          }}>
          {state.getThumbValueLabel(
            0
          )}
        </output>
      </div>
      {/* The track element holds the visible track line and the thumb. */}
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          position:
            'relative',
          height: TRACK_THICKNESS,
          width: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            position:
              'absolute',
            transform:
              'translate(-50%, -50%)',
            left: `${
              state.getThumbPercent(
                0
              ) * 100
            }%`,
            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"
  label="Hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

Vertical#

function ColorSlider(props) {
  let numberFormatter = useNumberFormatter({
    style: props.channel === 'alpha' ? 'percent' : 'decimal'
  });

  let state = useColorSliderState({...props, numberFormatter});
  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,
        touchAction: 'none'
      }}>
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          position: 'relative',
          width: TRACK_THICKNESS,
          height: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            position: 'absolute',
            transform: 'translate(-50%, -50%)',
            top: `${(1 - state.getThumbPercent(0)) * 100}%`,
            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"
  aria-label="Hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

function ColorSlider(props) {
  let numberFormatter = useNumberFormatter({
    style: props.channel === 'alpha' ? 'percent' : 'decimal'
  });

  let state = useColorSliderState({
    ...props,
    numberFormatter
  });
  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,
        touchAction: 'none'
      }}>
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          position: 'relative',
          width: TRACK_THICKNESS,
          height: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            position: 'absolute',
            transform: 'translate(-50%, -50%)',
            top: `${(1 - state.getThumbPercent(0)) * 100}%`,
            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"
  aria-label="Hue"
  defaultValue="hsl(0, 100%, 50%)"
/>

function ColorSlider(
  props
) {
  let numberFormatter = useNumberFormatter(
    {
      style:
        props.channel ===
        'alpha'
          ? 'percent'
          : 'decimal'
    }
  );

  let state = useColorSliderState(
    {
      ...props,
      numberFormatter
    }
  );
  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,
        touchAction:
          'none'
      }}>
      <div
        {...trackProps}
        ref={trackRef}
        style={{
          ...trackProps.style,
          position:
            'relative',
          width: TRACK_THICKNESS,
          height: '100%',
          borderRadius: 4
        }}>
        <div
          {...thumbProps}
          style={{
            ...thumbProps.style,
            position:
              'absolute',
            transform:
              'translate(-50%, -50%)',
            top: `${
              (1 -
                state.getThumbPercent(
                  0
                )) *
              100
            }%`,
            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"
  aria-label="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"
        label="Red"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="green"
        label="Green"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="blue"
        label="Blue"
        value={color}
        onChange={setColor}
      />
      <ColorSlider
        channel="alpha"
        label="Alpha"
        value={color}
        onChange={setColor}
      />
    </>
  );
}

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

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

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

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

HSLA#

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

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

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

HSBA#

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

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

function Example() {
  let [
    color,
    setColor
  ] = React.useState(
    parseColor(
      'hsb(0, 100%, 50%)'
    )
  );
  return (
    <>
      <ColorSlider
        channel="hue"
        label="Hue"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="saturation"
        label="Saturation"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="brightness"
        label="Brightness"
        value={color}
        onChange={
          setColor
        }
      />
      <ColorSlider
        channel="alpha"
        label="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'

Method	Description
`toFormat( (format: ColorFormat )): Color`
`toHexInt(): number`
`getChannelValue( (channel: ColorChannel )): number`
`withChannelValue( (channel: ColorChannel, , value: number )): Color`

A list of supported color formats.

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

'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( (c: Color )): 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.
`groupProps`	`HTMLAttributes<HTMLElement>`	Props for the group element wrapping the track and the thumb.
`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.