ColorArea

ColorArea allows users to adjust two channels of an RGB, HSL or HSB color value against a two-dimensional gradient background.

install	`yarn add @react-spectrum/color`
version	3.0.0-rc.1
usage	`import {ColorArea} from '@react-spectrum/color'`

View guidelines

Spectrum

Example#

<ColorArea defaultValue="#7f0000" />

<ColorArea defaultValue="#7f0000" />

<ColorArea defaultValue="#7f0000" />

Value#

A ColorArea 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. xChannel and yChannel props may also be provided to specify which color channels the color area should display, and the direction of each channel in the color gradient. 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 {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';

function Example() {
  let [value, setValue] = React.useState(parseColor('hsl(0, 100%, 50%)'));
  return (
    <Flex gap="size-300" wrap>
      <div>
        <Label id="hsl-uncontrolled-id">
          x: Saturation, y: Lightness (uncontrolled)
        </Label>
        <ColorArea
          aria-labelledby="hsl-uncontrolled-id"
          defaultValue={value}
          xChannel="saturation"
          yChannel="lightness"
        />
      </div>
      <div>
        <Label id="hsl-controlled-id">
          x: Saturation, y: Lightness (controlled)
        </Label>
        <ColorArea
          aria-labelledby="hsl-controlled-id"
          value={value}
          onChange={setValue}
          xChannel="saturation"
          yChannel="lightness"
        />
      </div>
    </Flex>
  );
}

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';

function Example() {
  let [value, setValue] = React.useState(
    parseColor('hsl(0, 100%, 50%)')
  );
  return (
    <Flex gap="size-300" wrap>
      <div>
        <Label id="hsl-uncontrolled-id">
          x: Saturation, y: Lightness (uncontrolled)
        </Label>
        <ColorArea
          aria-labelledby="hsl-uncontrolled-id"
          defaultValue={value}
          xChannel="saturation"
          yChannel="lightness"
        />
      </div>
      <div>
        <Label id="hsl-controlled-id">
          x: Saturation, y: Lightness (controlled)
        </Label>
        <ColorArea
          aria-labelledby="hsl-controlled-id"
          value={value}
          onChange={setValue}
          xChannel="saturation"
          yChannel="lightness"
        />
      </div>
    </Flex>
  );
}

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';

function Example() {
  let [value, setValue] =
    React.useState(
      parseColor(
        'hsl(0, 100%, 50%)'
      )
    );
  return (
    <Flex
      gap="size-300"
      wrap
    >
      <div>
        <Label id="hsl-uncontrolled-id">
          x: Saturation,
          y: Lightness
          (uncontrolled)
        </Label>
        <ColorArea
          aria-labelledby="hsl-uncontrolled-id"
          defaultValue={value}
          xChannel="saturation"
          yChannel="lightness"
        />
      </div>
      <div>
        <Label id="hsl-controlled-id">
          x: Saturation,
          y: Lightness
          (controlled)
        </Label>
        <ColorArea
          aria-labelledby="hsl-controlled-id"
          value={value}
          onChange={setValue}
          xChannel="saturation"
          yChannel="lightness"
        />
      </div>
    </Flex>
  );
}

HTML forms#

ColorArea supports the xName and yName props for integration with HTML forms. The values will be submitted as numbers between the minimum and maximum value for the corresponding channel in the X and Y direction.

<ColorArea xName="red" yName="green" />

<ColorArea xName="red" yName="green" />

<ColorArea
  xName="red"
  yName="green"
/>

Labeling#

By default, ColorArea uses an aria-label for the localized string "Color Picker", which labels the visually hidden <input> elements for the two color channels, or on mobile devices, the group containing them. If you wish to override this with a more specific label, an aria-label or aria-labelledby prop may be passed to further identify the element to assistive technologies. For example, for a ColorArea that adjusts a background color you might pass the aria-label prop, "Background color", which ColorArea will return as the aria-label prop "Background color, Color picker". If you provide your own aria-label or aria-labelledby, be sure to localize the string or labeling element appropriately.

Note that like ColorWheel, ColorArea does not include an integrated visible label or a label prop. Use aria-labelledby to label the ColorArea using the IDREF assigned to a visible label.

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';

<Flex gap="size-300" wrap alignItems="end">
  <ColorArea
    aria-label="Background color"
    defaultValue="hsl(0, 100%, 50%)"
    xChannel="saturation"
    yChannel="lightness" />
  <div>
    <Label
      id="hsl-aria-labelledby-id">Background color</Label>
    <ColorArea
      aria-labelledby="hsl-aria-labelledby-id"
      defaultValue="hsl(0, 100%, 50%)"
      xChannel="saturation"
      yChannel="lightness" />
  </div>
</Flex>

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';

<Flex gap="size-300" wrap alignItems="end">
  <ColorArea
    aria-label="Background color"
    defaultValue="hsl(0, 100%, 50%)"
    xChannel="saturation"
    yChannel="lightness" />
  <div>
    <Label
      id="hsl-aria-labelledby-id">Background color</Label>
    <ColorArea
      aria-labelledby="hsl-aria-labelledby-id"
      defaultValue="hsl(0, 100%, 50%)"
      xChannel="saturation"
      yChannel="lightness" />
  </div>
</Flex>

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';

<Flex
  gap="size-300"
  wrap
  alignItems="end"
>
  <ColorArea
    aria-label="Background color"
    defaultValue="hsl(0, 100%, 50%)"
    xChannel="saturation"
    yChannel="lightness"
  />
  <div>
    <Label id="hsl-aria-labelledby-id">
      Background color
    </Label>
    <ColorArea
      aria-labelledby="hsl-aria-labelledby-id"
      defaultValue="hsl(0, 100%, 50%)"
      xChannel="saturation"
      yChannel="lightness"
    />
  </div>
</Flex>

Accessibility#

Role description#

In order to communicate to a screen reader user that the ColorArea adjusts in two dimensions, ColorArea provides an aria-roledescription, using the localized string "2D Slider", on each of the visually hidden <input> elements.

Value formatting#

The aria-valuetext of each <input> element within the ColorArea is formatted according to the user's locale automatically. It will include the localized color channel name and current value for each channel, with the channel name and value that the <input> element controls coming before the channel name and value for the adjacent <input> element. For example, for an RGB ColorArea where the xChannel is "blue", the yChannel is "green", when the current selected color is yellow (rgb(255, 255, 0)), the <input> representing the blue channel will have aria-valuetext to announce as "Blue: 0, Green: 255", and the <input> representing the green channel will have aria-valuetext to announce as "Green: 255, Blue: 0".

Internationalization#

For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the ColorArea is automatically flipped. As mentioned previously, ColorArea automatically uses the current locale to format the aria-valuetext for each of the <input> element with the channel name and current value.

Events#

ColorArea supports two events: onChange and onChangeEnd. onChange is triggered whenever the ColorArea'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 ColorArea's value.

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

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

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

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

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

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

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

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

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

Creating a color picker#

To build a fully functional color picker, combine a ColorArea, which adjusts two channels of a color value stored in state, with a separate control, like a ColorSlider or ColorWheel, for adjusting the value of the third channel within the color space for the color value stored in state. The current color space for a color can be returned using the color.getColorSpace method. An array of channel names for a color can be returned using the color.getColorChannels method. To get a localized channel name to use as a label, you can use the color.getChannelName method.

RGBA#

This example shows how you could build an RGB color picker using a color area and 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 both the ColorArea and ColorSlider are used to make the components controlled, so that they both update when the color is modified.

import {ColorArea, ColorSlider} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';

function Example() {
  let [color, setColor] = React.useState(parseColor('#ff00ff'));
  let [redChannel, greenChannel, blueChannel] = color.getColorChannels();
  return (
    <fieldset style={{ border: 0 }}>
      <legend>{color.getColorSpace().toUpperCase()}A Example</legend>
      <Flex direction="column">
        <ColorArea
          xChannel={redChannel}
          yChannel={greenChannel}
          value={color}
          onChange={setColor}
        />
        <ColorSlider channel={blueChannel} value={color} onChange={setColor} />
        <ColorSlider channel="alpha" value={color} onChange={setColor} />
        <p>Current value: {color.toString('css')}</p>
      </Flex>
    </fieldset>
  );
}

import {
  ColorArea,
  ColorSlider
} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';

function Example() {
  let [color, setColor] = React.useState(
    parseColor('#ff00ff')
  );
  let [redChannel, greenChannel, blueChannel] = color
    .getColorChannels();
  return (
    <fieldset style={{ border: 0 }}>
      <legend>
        {color.getColorSpace().toUpperCase()}A Example
      </legend>
      <Flex direction="column">
        <ColorArea
          xChannel={redChannel}
          yChannel={greenChannel}
          value={color}
          onChange={setColor}
        />
        <ColorSlider
          channel={blueChannel}
          value={color}
          onChange={setColor}
        />
        <ColorSlider
          channel="alpha"
          value={color}
          onChange={setColor}
        />
        <p>Current value: {color.toString('css')}</p>
      </Flex>
    </fieldset>
  );
}

import {
  ColorArea,
  ColorSlider
} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';

function Example() {
  let [color, setColor] =
    React.useState(
      parseColor(
        '#ff00ff'
      )
    );
  let [
    redChannel,
    greenChannel,
    blueChannel
  ] = color
    .getColorChannels();
  return (
    <fieldset
      style={{
        border: 0
      }}
    >
      <legend>
        {color
          .getColorSpace()
          .toUpperCase()}A
        Example
      </legend>
      <Flex direction="column">
        <ColorArea
          xChannel={redChannel}
          yChannel={greenChannel}
          value={color}
          onChange={setColor}
        />
        <ColorSlider
          channel={blueChannel}
          value={color}
          onChange={setColor}
        />
        <ColorSlider
          channel="alpha"
          value={color}
          onChange={setColor}
        />
        <p>
          Current value:
          {' '}
          {color
            .toString(
              'css'
            )}
        </p>
      </Flex>
    </fieldset>
  );
}

HSLA#

This example shows how to build a similar color picker to the one above, using HSLA colors instead, and a ColorWheel instead of a ColorSlider for the Hue channel.

import {ColorArea, ColorSlider, ColorWheel} from '@react-spectrum/color';
import {Flex, Grid} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';
import {View} from '@react-spectrum/view';

function Example() {
  let [color, setColor] = React.useState(parseColor('hsla(0, 100%, 50%, 0.5)'));
  let [, saturationChannel, lightnessChannel] = color.getColorChannels();
  return (
    <fieldset style={{border: 0}}>
      <legend>HSLA Example</legend>
      <Flex
        direction="column">
        <View
          position="relative"
          width="size-2400">
          <Grid
            position="absolute"
            justifyContent="center"
            alignContent="center"
            width="100%"
            height="100%">
            <ColorArea
              xChannel={saturationChannel}
              yChannel={lightnessChannel}
              value={color}
              onChange={setColor}
              size="size-1200" />
          </Grid>
          <ColorWheel
            value={color}
            onChange={setColor}
            size="size-2400" />
        </View>
        <ColorSlider channel="alpha" value={color} onChange={setColor} />
        <p>Current value: {color.toString('hsla')}</p>
      </Flex>
    </fieldset>
  );
}

import {
  ColorArea,
  ColorSlider,
  ColorWheel
} from '@react-spectrum/color';
import {Flex, Grid} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';
import {View} from '@react-spectrum/view';

function Example() {
  let [color, setColor] = React.useState(
    parseColor('hsla(0, 100%, 50%, 0.5)')
  );
  let [, saturationChannel, lightnessChannel] = color
    .getColorChannels();
  return (
    <fieldset style={{ border: 0 }}>
      <legend>HSLA Example</legend>
      <Flex direction="column">
        <View
          position="relative"
          width="size-2400"
        >
          <Grid
            position="absolute"
            justifyContent="center"
            alignContent="center"
            width="100%"
            height="100%"
          >
            <ColorArea
              xChannel={saturationChannel}
              yChannel={lightnessChannel}
              value={color}
              onChange={setColor}
              size="size-1200"
            />
          </Grid>
          <ColorWheel
            value={color}
            onChange={setColor}
            size="size-2400"
          />
        </View>
        <ColorSlider
          channel="alpha"
          value={color}
          onChange={setColor}
        />
        <p>Current value: {color.toString('hsla')}</p>
      </Flex>
    </fieldset>
  );
}

import {
  ColorArea,
  ColorSlider,
  ColorWheel
} from '@react-spectrum/color';
import {
  Flex,
  Grid
} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';
import {View} from '@react-spectrum/view';

function Example() {
  let [color, setColor] =
    React.useState(
      parseColor(
        'hsla(0, 100%, 50%, 0.5)'
      )
    );
  let [
    ,
    saturationChannel,
    lightnessChannel
  ] = color
    .getColorChannels();
  return (
    <fieldset
      style={{
        border: 0
      }}
    >
      <legend>
        HSLA Example
      </legend>
      <Flex direction="column">
        <View
          position="relative"
          width="size-2400"
        >
          <Grid
            position="absolute"
            justifyContent="center"
            alignContent="center"
            width="100%"
            height="100%"
          >
            <ColorArea
              xChannel={saturationChannel}
              yChannel={lightnessChannel}
              value={color}
              onChange={setColor}
              size="size-1200"
            />
          </Grid>
          <ColorWheel
            value={color}
            onChange={setColor}
            size="size-2400"
          />
        </View>
        <ColorSlider
          channel="alpha"
          value={color}
          onChange={setColor}
        />
        <p>
          Current value:
          {' '}
          {color
            .toString(
              'hsla'
            )}
        </p>
      </Flex>
    </fieldset>
  );
}

HSBA#

This example shows how to build an HSBA color picker.

import {ColorArea, ColorSlider, ColorWheel} from '@react-spectrum/color';
import {Flex, Grid} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';
import {View} from '@react-spectrum/view';

function Example() {
  let [color, setColor] = React.useState(parseColor('hsba(0, 100%, 50%, 0.5)'));
  let [, saturationChannel, brightnessChannel] = color.getColorChannels();
  return (
    <fieldset style={{border: 0}}>
      <legend>HSBA Example</legend>
      <Flex
        direction="column">
        <View
          position="relative"
          width="size-2400">
          <Grid
            position="absolute"
            justifyContent="center"
            alignContent="center"
            width="100%"
            height="100%">
            <ColorArea
              xChannel={saturationChannel}
              yChannel={brightnessChannel}
              value={color}
              onChange={setColor}
              size="size-1200" />
          </Grid>
          <ColorWheel
            value={color}
            onChange={setColor}
            size="size-2400" />
        </View>
        <ColorSlider channel="alpha" value={color} onChange={setColor} />
        <p>Current value: {color.toString('hsba')}</p>
      </Flex>
    </fieldset>
  );
}

import {
  ColorArea,
  ColorSlider,
  ColorWheel
} from '@react-spectrum/color';
import {Flex, Grid} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';
import {View} from '@react-spectrum/view';

function Example() {
  let [color, setColor] = React.useState(
    parseColor('hsba(0, 100%, 50%, 0.5)')
  );
  let [, saturationChannel, brightnessChannel] = color
    .getColorChannels();
  return (
    <fieldset style={{ border: 0 }}>
      <legend>HSBA Example</legend>
      <Flex direction="column">
        <View
          position="relative"
          width="size-2400"
        >
          <Grid
            position="absolute"
            justifyContent="center"
            alignContent="center"
            width="100%"
            height="100%"
          >
            <ColorArea
              xChannel={saturationChannel}
              yChannel={brightnessChannel}
              value={color}
              onChange={setColor}
              size="size-1200"
            />
          </Grid>
          <ColorWheel
            value={color}
            onChange={setColor}
            size="size-2400"
          />
        </View>
        <ColorSlider
          channel="alpha"
          value={color}
          onChange={setColor}
        />
        <p>Current value: {color.toString('hsba')}</p>
      </Flex>
    </fieldset>
  );
}

import {
  ColorArea,
  ColorSlider,
  ColorWheel
} from '@react-spectrum/color';
import {
  Flex,
  Grid
} from '@react-spectrum/layout';
import {Label} from '@react-spectrum/label';
import {parseColor} from '@react-stately/color';
import {View} from '@react-spectrum/view';

function Example() {
  let [color, setColor] =
    React.useState(
      parseColor(
        'hsba(0, 100%, 50%, 0.5)'
      )
    );
  let [
    ,
    saturationChannel,
    brightnessChannel
  ] = color
    .getColorChannels();
  return (
    <fieldset
      style={{
        border: 0
      }}
    >
      <legend>
        HSBA Example
      </legend>
      <Flex direction="column">
        <View
          position="relative"
          width="size-2400"
        >
          <Grid
            position="absolute"
            justifyContent="center"
            alignContent="center"
            width="100%"
            height="100%"
          >
            <ColorArea
              xChannel={saturationChannel}
              yChannel={brightnessChannel}
              value={color}
              onChange={setColor}
              size="size-1200"
            />
          </Grid>
          <ColorWheel
            value={color}
            onChange={setColor}
            size="size-2400"
          />
        </View>
        <ColorSlider
          channel="alpha"
          value={color}
          onChange={setColor}
        />
        <p>
          Current value:
          {' '}
          {color
            .toString(
              'hsba'
            )}
        </p>
      </Flex>
    </fieldset>
  );
}

Props#

Name	Type	Description
`size`	`DimensionValue`	Size of the Color Area.
`xName`	`string`	The name of the x channel input element, used when submitting an HTML form. See MDN.
`yName`	`string`	The name of the y channel input element, used when submitting an HTML form. See MDN.
`colorSpace`	`ColorSpace`	The color space that the color area operates in. The `xChannel` and `yChannel` must be in this color space. If not provided, this defaults to the color space of the `color` or `defaultColor` value.
`xChannel`	`ColorChannel`	Color channel for the horizontal axis.
`yChannel`	`ColorChannel`	Color channel for the vertical axis.
`isDisabled`	`boolean`	Whether the ColorArea is disabled.
`value`	`T`	The current value (controlled).
`defaultValue`	`T`	The default value (uncontrolled).

Events

Name	Type	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	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	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	Description
`minWidth`	`Responsive<DimensionValue>`	The minimum width of the element. See MDN.
`maxWidth`	`Responsive<DimensionValue>`	The maximum width 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	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	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	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

import {ColorArea} from '@react-spectrum/color';

<ColorArea defaultValue="#7f0000" isDisabled />

import {ColorArea} from '@react-spectrum/color';

<ColorArea defaultValue="#7f0000" isDisabled />

import {ColorArea} from '@react-spectrum/color';

<ColorArea
  defaultValue="#7f0000"
  isDisabled
/>

Custom Size#

View guidelines

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';

<Flex direction="column" gap="size-300">
  <ColorArea defaultValue="#7f0000" size="size-3600" maxWidth="100%" />
</Flex>

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';

<Flex direction="column" gap="size-300">
  <ColorArea
    defaultValue="#7f0000"
    size="size-3600"
    maxWidth="100%"
  />
</Flex>

import {ColorArea} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';

<Flex
  direction="column"
  gap="size-300"
>
  <ColorArea
    defaultValue="#7f0000"
    size="size-3600"
    maxWidth="100%"
  />
</Flex>

Testing#

The ColorArea 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.

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.
`clone(): Color`	Returns a duplicate of the color value.
`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.
`getChannelFormatOptions( (channel: ColorChannel )): Intl.NumberFormatOptions`	Returns the number formatting options for the given channel.
`formatChannelValue( (channel: ColorChannel, , locale: string )): string`	Formats the numeric value for a given channel for display according to the provided locale.
`getColorSpace(): ColorSpace`	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.
`getColorName( (locale: string )): string`	Returns a localized name for the color, for use in visual or accessibility labels.
`getHueName( (locale: string )): string`	Returns a localized name for the hue, for use in visual or accessibility labels.

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.