beta

ColorSlider

ColorSliders allow users to adjust an individual channel of a color value.

install	`yarn add @react-spectrum/color`
version	3.0.0-beta.15
usage	`import {ColorSlider} from '@react-spectrum/color'`

View guidelines

Example#

<ColorSlider defaultValue="#7f0000" channel="red" />

<ColorSlider defaultValue="#7f0000" channel="red" />

<ColorSlider
  defaultValue="#7f0000"
  channel="red"
/>

Value#

A ColorSlider requires either an uncontrolled default value or a controlled value, provided using the defaultValue or value props respectively. The value provided to either of these props should be a color string or Color object. The channel prop must also be provided to specify which color channel the slider should display. This must be one of the channels included in the color value, for example, for RGB colors, the "red", "green", and "blue" channels are available. For a full list of supported channels, see the Props table below.

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(0, 100%, 50%)'));
  return (
    <Flex gap="size-300" wrap>
      <ColorSlider
        label="Hue (uncontrolled)"
        defaultValue="hsl(0, 100%, 50%)"
        channel="hue" />
      <ColorSlider
        label="Hue (controlled)"
        value={value}
        onChange={setValue}
        channel="hue" />
    </Flex>
  );
}

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

function Example() {
  let [value, setValue] = React.useState(
    parseColor('hsl(0, 100%, 50%)')
  );
  return (
    <Flex gap="size-300" wrap>
      <ColorSlider
        label="Hue (uncontrolled)"
        defaultValue="hsl(0, 100%, 50%)"
        channel="hue"
      />
      <ColorSlider
        label="Hue (controlled)"
        value={value}
        onChange={setValue}
        channel="hue"
      />
    </Flex>
  );
}

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

function Example() {
  let [value, setValue] =
    React.useState(
      parseColor(
        'hsl(0, 100%, 50%)'
      )
    );
  return (
    <Flex
      gap="size-300"
      wrap
    >
      <ColorSlider
        label="Hue (uncontrolled)"
        defaultValue="hsl(0, 100%, 50%)"
        channel="hue"
      />
      <ColorSlider
        label="Hue (controlled)"
        value={value}
        onChange={setValue}
        channel="hue"
      />
    </Flex>
  );
}

Labeling#

The ColorSlider's channel name and value are shown above the ColorSlider by default. The label and value label can be hidden by providing label={null} and showValueLabel={false} to the ColorSlider, respectively. In addition, a custom label can be provided via the label prop.

<Flex gap="size-300" wrap alignItems="flex-end">
  <ColorSlider
    channel="saturation"
    defaultValue="hsl(0, 100%, 50%)"
    label={null}
  />
  <ColorSlider
    channel="lightness"
    defaultValue="hsl(0, 100%, 50%)"
    showValueLabel={false}
  />
</Flex>

<Flex gap="size-300" wrap alignItems="flex-end">
  <ColorSlider
    channel="saturation"
    defaultValue="hsl(0, 100%, 50%)"
    label={null}
  />
  <ColorSlider
    channel="lightness"
    defaultValue="hsl(0, 100%, 50%)"
    showValueLabel={false}
  />
</Flex>

<Flex
  gap="size-300"
  wrap
  alignItems="flex-end"
>
  <ColorSlider
    channel="saturation"
    defaultValue="hsl(0, 100%, 50%)"
    label={null}
  />
  <ColorSlider
    channel="lightness"
    defaultValue="hsl(0, 100%, 50%)"
    showValueLabel={false}
  />
</Flex>

Accessibility#

If the ColorSlider's label is hidden, a localized string for the channel name is used as the aria-label by default. The value of the ColorSlider is also automatically localized and provided to the input as aria-valuetext regardless of the value label's visibility. If you provide your own aria-label or aria-labelledby, be sure to localize the string or labeling element appropriately.

Internationalization#

For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the ColorSlider is automatically flipped. As mentioned previously, ColorSlider automatically uses the current locale to format the channel and value label.

Events#

ColorSlider supports two events: onChange and onChangeEnd. onChange is triggered whenever the ColorSlider'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 ColorSlider'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>
      <ColorSlider
        value={currentValue}
        channel="hue"
        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>
      <ColorSlider
        value={currentValue}
        channel="hue"
        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>
      <ColorSlider
        value={currentValue}
        channel="hue"
        onChange={setCurrentValue}
        onChangeEnd={setFinalValue}
      />
      <pre>Current value: {currentValue.toString('hsl')}</pre>
      <pre>Final value: {finalValue.toString('hsl')}</pre>
    </div>
  );
}

Creating a color picker#

RGBA#

This example shows how you could build an RGBA color picker using four color sliders bound to the same color value in state. The parseColor function is used to parse the initial color from a hex value, stored in state. The value and onChange props of ColorSlider are used to make the sliders controlled, so that they all update when the color is modified.

function Example() {
  let [color, setColor] = React.useState(parseColor('#ff00ff'));

  return (
    <Flex direction="column">
      <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} />
    </Flex>
  );
}

function Example() {
  let [color, setColor] = React.useState(
    parseColor('#ff00ff')
  );

  return (
    <Flex direction="column">
      <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}
      />
    </Flex>
  );
}

function Example() {
  let [color, setColor] =
    React.useState(
      parseColor(
        '#ff00ff'
      )
    );

  return (
    <Flex direction="column">
      <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}
      />
    </Flex>
  );
}

HSLA#

This example shows how to build a similar color picker to the one above, using HSLA colors instead.

function Example() {
  let [color, setColor] = React.useState(parseColor('hsla(0, 100%, 50%, 0.5)'));

  return (
    <Flex direction="column">
      <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} />
    </Flex>
  );
}

function Example() {
  let [color, setColor] = React.useState(
    parseColor('hsla(0, 100%, 50%, 0.5)')
  );

  return (
    <Flex direction="column">
      <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}
      />
    </Flex>
  );
}

function Example() {
  let [color, setColor] =
    React.useState(
      parseColor(
        'hsla(0, 100%, 50%, 0.5)'
      )
    );

  return (
    <Flex direction="column">
      <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}
      />
    </Flex>
  );
}

HSBA#

This example shows how to build an HSBA color picker.

function Example() {
  let [color, setColor] = React.useState(parseColor('hsba(0, 100%, 50%, 0.5)'));
  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('hsba(0, 100%, 50%, 0.5)')
  );
  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(
        'hsba(0, 100%, 50%, 0.5)'
      )
    );
  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}
      />
    </>
  );
}

Props#

Name	Type	Default	Description
`channel`	`ColorChannel`	—	The color channel that the slider manipulates.
`showValueLabel`	`boolean`	—	Whether the value label is displayed. True by default if there is a label, false by default if not.
`contextualHelp`	`ReactNode`	—	A ContextualHelp element to place next to the label.
`orientation`	`Orientation`	`'horizontal'`	The orientation of the Slider.
`isDisabled`	`boolean`	—	Whether the whole Slider is disabled.
`value`	`T`	—	The current value (controlled).
`defaultValue`	`T`	—	The default value (uncontrolled).
`label`	`ReactNode`	—	The content to display as the label.

Events

Name	Type	Default	Description
`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.

Layout

Name	Type	Default	Description
`flex`	`Responsive<string \| number \| boolean>`	—	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`Responsive<number \| string>`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'stretch'>`	—	Overrides the `alignItems` property of a flex or grid container. See MDN.
`justifySelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'>`	—	Specifies how the element is justified inside a flex or grid container. See MDN.
`order`	`Responsive<number>`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`Responsive<string>`	—	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`Responsive<string>`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`Responsive<string>`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`Responsive<DimensionValue>`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`Responsive<DimensionValue>`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`Responsive<DimensionValue>`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`Responsive<DimensionValue>`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`Responsive<DimensionValue>`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`Responsive<DimensionValue>`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`Responsive<DimensionValue>`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`Responsive<DimensionValue>`	—	The width of the element. See MDN.
`minWidth`	`Responsive<DimensionValue>`	—	The minimum width of the element. See MDN.
`maxWidth`	`Responsive<DimensionValue>`	—	The maximum width of the element. See MDN.
`height`	`Responsive<DimensionValue>`	—	The height of the element. See MDN.
`minHeight`	`Responsive<DimensionValue>`	—	The minimum height of the element. See MDN.
`maxHeight`	`Responsive<DimensionValue>`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`Responsive<'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'>`	—	Specifies how the element is positioned. See MDN.
`top`	`Responsive<DimensionValue>`	—	The top position for the element. See MDN.
`bottom`	`Responsive<DimensionValue>`	—	The bottom position for the element. See MDN.
`left`	`Responsive<DimensionValue>`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`Responsive<DimensionValue>`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`Responsive<DimensionValue>`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`Responsive<DimensionValue>`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`Responsive<number>`	—	The stacking order for the element. See MDN.
`isHidden`	`Responsive<boolean>`	—	Hides the element.

Accessibility

Name	Type	Default	Description
`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.

Advanced

Name	Type	Default	Description
`UNSAFE_className`	`string`	—	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	—	Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

Disabled#

View guidelines

<ColorSlider defaultValue="#7f0000" channel="red" isDisabled />

<ColorSlider
  defaultValue="#7f0000"
  channel="red"
  isDisabled
/>

<ColorSlider
  defaultValue="#7f0000"
  channel="red"
  isDisabled
/>

Vertical#

View guidelines

<ColorSlider defaultValue="#7f0000" channel="red" orientation="vertical" />

<ColorSlider
  defaultValue="#7f0000"
  channel="red"
  orientation="vertical"
/>

<ColorSlider
  defaultValue="#7f0000"
  channel="red"
  orientation="vertical"
/>

Custom Size#

View guidelines

<Flex direction="column" gap="size-300">
  <ColorSlider
    defaultValue="#7f0000"
    channel="red"
    orientation="vertical"
    height="size-3600"
  />
  <ColorSlider
    defaultValue="#7f0000"
    channel="red"
    width="size-3600"
    maxWidth="100%"
  />
</Flex>

<Flex direction="column" gap="size-300">
  <ColorSlider
    defaultValue="#7f0000"
    channel="red"
    orientation="vertical"
    height="size-3600"
  />
  <ColorSlider
    defaultValue="#7f0000"
    channel="red"
    width="size-3600"
    maxWidth="100%"
  />
</Flex>

<Flex
  direction="column"
  gap="size-300"
>
  <ColorSlider
    defaultValue="#7f0000"
    channel="red"
    orientation="vertical"
    height="size-3600"
  />
  <ColorSlider
    defaultValue="#7f0000"
    channel="red"
    width="size-3600"
    maxWidth="100%"
  />
</Flex>

Method	Description
`toFormat( (format: ColorFormat )): Color`	Converts the color to the given color format, and returns a new Color object.
`toString( (format: ColorFormat \| \| 'css' )): string`	Converts the color to a string in the given format.
`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.
`getColorSpace(): ColorFormat`	Returns the color space, 'rgb', 'hsb' or 'hsl', for the current color.
`getColorSpaceAxes( (xyChannels: {xChannel?: ColorChannel, yChannel?: ColorChannel } )): ColorAxes`	Returns the color space axes, xChannel, yChannel, zChannel.
`getColorChannels(): [ ColorChannel, ColorChannel, ColorChannel ]`	Returns an array of the color channels within the current color space space.

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.
`pageSize`	`number`	The page step value of the color channel, used when incrementing and decrementing.