beta

ColorSlider

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

installyarn add @react-spectrum/color
version3.0.0-beta.34
usageimport {ColorSlider} from '@react-spectrum/color'

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>
  );
}

HTML forms#

ColorSlider supports the name prop for integration with HTML forms. The value will be submitted as a number between the minimum and maximum value for the displayed channel.

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

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="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="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="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#


NameTypeDefaultDescription
channelColorChannelThe color channel that the slider manipulates.
showValueLabelbooleanWhether the value label is displayed. True by default if there is a label, false by default if not.
contextualHelpReactNodeA ContextualHelp element to place next to the label.
colorSpaceColorSpace

The color space that the slider operates in. The channel must be in this color space. If not provided, this defaults to the color space of the color or defaultColor value.

orientationOrientation'horizontal'The orientation of the Slider.
isDisabledbooleanWhether the whole Slider is disabled.
valueTThe current value (controlled).
defaultValueTThe default value (uncontrolled).
labelReactNodeThe content to display as the label.
namestringThe name of the input element, used when submitting an HTML form. See MDN.
Events
NameTypeDescription
onChange( (value: Color )) => voidHandler that is called when the value changes, as the user drags.
onChangeEnd( (value: Color )) => voidHandler that is called when the user stops dragging.
Layout
NameTypeDescription
flexResponsive<stringnumberboolean>When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
flexGrowResponsive<number>When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
flexShrinkResponsive<number>When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
flexBasisResponsive<numberstring>When used in a flex layout, specifies the initial main size of the element. See MDN.
alignSelfResponsive<'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.
justifySelfResponsive<'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.
orderResponsive<number>The layout order for the element within a flex or grid container. See MDN.
gridAreaResponsive<string>When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
gridColumnResponsive<string>When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
gridRowResponsive<string>When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
gridColumnStartResponsive<string>When used in a grid layout, specifies the starting column to span within the grid. See MDN.
gridColumnEndResponsive<string>When used in a grid layout, specifies the ending column to span within the grid. See MDN.
gridRowStartResponsive<string>When used in a grid layout, specifies the starting row to span within the grid. See MDN.
gridRowEndResponsive<string>When used in a grid layout, specifies the ending row to span within the grid. See MDN.
Spacing
NameTypeDescription
marginResponsive<DimensionValue>The margin for all four sides of the element. See MDN.
marginTopResponsive<DimensionValue>The margin for the top side of the element. See MDN.
marginBottomResponsive<DimensionValue>The margin for the bottom side of the element. See MDN.
marginStartResponsive<DimensionValue>The margin for the logical start side of the element, depending on layout direction. See MDN.
marginEndResponsive<DimensionValue>The margin for the logical end side of an element, depending on layout direction. See MDN.
marginXResponsive<DimensionValue>The margin for both the left and right sides of the element. See MDN.
marginYResponsive<DimensionValue>The margin for both the top and bottom sides of the element. See MDN.
Sizing
NameTypeDescription
widthResponsive<DimensionValue>The width of the element. See MDN.
minWidthResponsive<DimensionValue>The minimum width of the element. See MDN.
maxWidthResponsive<DimensionValue>The maximum width of the element. See MDN.
heightResponsive<DimensionValue>The height of the element. See MDN.
minHeightResponsive<DimensionValue>The minimum height of the element. See MDN.
maxHeightResponsive<DimensionValue>The maximum height of the element. See MDN.
Positioning
NameTypeDescription
positionResponsive<'static''relative''absolute''fixed''sticky'>Specifies how the element is positioned. See MDN.
topResponsive<DimensionValue>The top position for the element. See MDN.
bottomResponsive<DimensionValue>The bottom position for the element. See MDN.
leftResponsive<DimensionValue>The left position for the element. See MDN. Consider using start instead for RTL support.
rightResponsive<DimensionValue>The right position for the element. See MDN. Consider using start instead for RTL support.
startResponsive<DimensionValue>The logical start position for the element, depending on layout direction. See MDN.
endResponsive<DimensionValue>The logical end position for the element, depending on layout direction. See MDN.
zIndexResponsive<number>The stacking order for the element. See MDN.
isHiddenResponsive<boolean>Hides the element.
Accessibility
NameTypeDescription
idstringThe element's unique identifier. See MDN.
aria-labelstringDefines a string value that labels the current element.
aria-labelledbystringIdentifies the element (or elements) that labels the current element.
aria-describedbystringIdentifies the element (or elements) that describes the object.
aria-detailsstringIdentifies the element (or elements) that provide a detailed, extended description for the object.
Advanced
NameTypeDescription
UNSAFE_classNamestringSets the CSS className for the element. Only use as a last resort. Use style props instead.
UNSAFE_styleCSSPropertiesSets 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>

Contextual help#

A ContextualHelp element may be placed next to the label to provide additional information or help about a ColorSlider.

import {Content, ContextualHelp, Heading} from '@adobe/react-spectrum';

<ColorSlider
  label="Accent Color"
  channel="hue"
  defaultValue="hsl(120, 100%, 50%)"
  contextualHelp={
    <ContextualHelp>
      <Heading>What is an accent color?</Heading>
      <Content>
        An accent color is the primary foreground color for your theme, used
        across all components.
      </Content>
    </ContextualHelp>
  }
/>
import {
  Content,
  ContextualHelp,
  Heading
} from '@adobe/react-spectrum';

<ColorSlider
  label="Accent Color"
  channel="hue"
  defaultValue="hsl(120, 100%, 50%)"
  contextualHelp={
    <ContextualHelp>
      <Heading>What is an accent color?</Heading>
      <Content>
        An accent color is the primary foreground color
        for your theme, used across all components.
      </Content>
    </ContextualHelp>
  }
/>
import {
  Content,
  ContextualHelp,
  Heading
} from '@adobe/react-spectrum';

<ColorSlider
  label="Accent Color"
  channel="hue"
  defaultValue="hsl(120, 100%, 50%)"
  contextualHelp={
    <ContextualHelp>
      <Heading>
        What is an
        accent color?
      </Heading>
      <Content>
        An accent color
        is the primary
        foreground
        color for your
        theme, used
        across all
        components.
      </Content>
    </ContextualHelp>
  }
/>

Testing#


The ColorSlider features a draggable handle that the user can interact with to change its color value. Please see the following section in the testing docs for more information on how to simulate this action in your test suite.

Simulating move event

Please also refer to React Spectrum's test suite if you find that the above isn't sufficient when resolving issues in your own test cases.