{/* Copyright 2024 Adobe. All rights reserved.
This file is licensed to you under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License. You may obtain a copy
of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
OF ANY KIND, either express or implied. See the License for the specific language
governing permissions and limitations under the License. */}

import {Layout} from '@react-spectrum/docs';
export default Layout;

import docs from 'docs:react-aria-components';
import statelyDocs from 'docs:@react-stately/color';
import {PropTable, HeaderInfo, TypeLink, PageDescription, StateTable, ContextTable} from '@react-spectrum/docs';
import styles from '@react-spectrum/docs/src/docs.css';
import packageData from 'react-aria-components/package.json';
import Anatomy from '/packages/react-aria/docs/color/ColorAreaAnatomy.svg';
import ChevronRight from '@spectrum-icons/workflow/ChevronRight';
import {Divider} from '@react-spectrum/divider';
import {ExampleList} from '@react-spectrum/docs/src/ExampleList';
import {ExampleCard} from '@react-spectrum/docs/src/ExampleCard';
import Label from '@react-spectrum/docs/pages/assets/component-illustrations/Label.svg';
import {Keyboard} from '@react-spectrum/text';
import {StarterKits} from '@react-spectrum/docs/src/StarterKits';

---
category: Color
keywords: [color area, color picker, aria]
type: component
---

# ColorArea

<PageDescription>{docs.exports.ColorArea.description}</PageDescription>

<HeaderInfo
  packageData={packageData}
  componentNames={['ColorArea']}
  sourceData={[
    {type: 'W3C', url: 'https://www.w3.org/WAI/ARIA/apg/patterns/slider/'}
  ]} />

## Example

```tsx example
import {ColorArea, ColorThumb} from 'react-aria-components';

<ColorArea>
  <ColorThumb />
</ColorArea>
```

<details>
  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>

```css hidden
@import "./ColorSlider.mdx";
```

```css
.react-aria-ColorArea {
  width: 192px;
  height: 192px;
  border-radius: 4px;
  flex-shrink: 0;
}

.react-aria-ColorThumb {
  border: 2px solid white;
  box-shadow: 0 0 0 1px black, inset 0 0 0 1px black;
  width: 20px;
  height: 20px;
  border-radius: 50%;
  box-sizing: border-box;

  &[data-focus-visible] {
    width: 24px;
    height: 24px;
  }
}
```

</details>

## Features

The [&lt;input type="color"&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color) HTML element
can be used to build a color picker, however it is very inconsistent across browsers and operating systems and consists
of a complete color picker rather than a color area. `ColorArea` helps achieve accessible and
touch-friendly color areas that can be styled as needed.

* **Customizable** – Support for adjusting two-channel values of an HSL, HSB or RGB color value.
* **High quality interactions** – Mouse, touch, and keyboard input is supported via the [useMove](../react-aria/useMove.html) hook. Pressing the color area moves the thumb to that position. Text selection and touch scrolling are prevented while dragging.
* **Accessible** – Announces localized color descriptions for screen reader users (e.g. "dark vibrant blue"). Uses two visually hidden `<input>` elements for mobile screen reader support and HTML form integration.

## Anatomy

<Anatomy
  role="img"
  aria-label="Color area anatomy diagram: Shows a color area component with labels pointing to its parts, including the area, and thumb elements." />

A color area consists of a rectangular background area that provides, using a two-dimensional gradient,
a visual representation of the range of color values from which a user can select, and a thumb that the user can drag
to change the selected color value. Two visually hidden `<input>` elements are used to represent the color channel
values to assistive technologies.

```tsx
import {ColorArea, ColorThumb} from 'react-aria-components';

<ColorArea>
  <ColorThumb />
</ColorArea>
```

{/*

## Examples

<ExampleList tag="colorslider" />

*/}

## Starter kits

To help kick-start your project, we offer starter kits that include example implementations of all React Aria components with various styling solutions. All components are fully styled, including support for dark mode, high contrast mode, and all UI states. Each starter comes with a pre-configured [Storybook](https://storybook.js.org/) that you can experiment with, or use as a starting point for your own component library.

<StarterKits component="colorarea" />

## Reusable wrappers

If you will use a ColorArea in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

```tsx example export=true
import type {ColorAreaProps} from 'react-aria-components';

export function MyColorArea(props: ColorAreaProps) {
  return (
    <ColorArea {...props}>
      <ColorThumb />
    </ColorArea>
  );
}

<MyColorArea defaultValue="hsl(30, 100%, 50%)" />
```

## 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 <TypeLink links={docs.links} type={docs.exports.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](#props) table below.

### Uncontrolled

By default, color area is uncontrolled, with a default value of white using the RGB color space (`rgb(255, 255, 255)`).
You can change the default value using the `defaultValue` prop, and the color area will use the color space of the provided value.

```tsx example
<MyColorArea defaultValue="hsb(219, 58%, 93%)" />
```

If no `xChannel` or `yChannel` is provided, for the RGB color space, the `red` color channel maps to the horizontal axis or `xChannel`,
and the `green` color channel maps to the vertical axis or `yChannel`. Similarly, for the HSL and HSB color spaces, the `hue` color
channel maps to the horizontal axis or `xChannel`, and the `saturation` color channel maps to the vertical axis or `yChannel`.

### Controlled

In the example below, the <TypeLink links={docs.links} type={docs.exports.parseColor} /> function is used to parse the initial color from an HSL string. This is passed to the `value` prop to make the `ColorArea` controlled, and updated in the `onChange` event.

```tsx example
import {parseColor} from 'react-aria-components';

function Example() {
  let [value, setValue] = React.useState(parseColor('hsl(0, 100%, 50%)'));
  return (
    <>
      <MyColorArea
        value={value}
        onChange={setValue}
        xChannel="saturation"
        yChannel="lightness" />
      <p>Value: {value.toString('hex')}</p>
    </>
  );
}
```

### 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.

```tsx example
<MyColorArea xName="red" yName="green" />
```

## 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 <TypeLink links={docs.links} type={docs.exports.Color} /> object
as a parameter.

The example below uses `onChange` and `onChangeEnd` to update two separate elements with the ColorArea's value.

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

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

## Creating a color picker

To build a fully functional color picker, combine a ColorArea, which adjusts two channels of a color value, with a separate control, like a [ColorSlider](ColorSlider.html) or [ColorWheel](ColorWheel.html), to adjust the value of the third channel.

```tsx example
import {ColorSlider, Label, SliderOutput, SliderTrack} from 'react-aria-components';

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

  return (
    <div>
      <MyColorArea
        value={color}
        onChange={setColor}
        xChannel="saturation"
        yChannel="lightness" />
      <ColorSlider channel="hue" value={color} onChange={setColor} style={{width: 192, marginTop: 8}}>
        <Label />
        <SliderOutput />
        <SliderTrack>
          <ColorThumb />
        </SliderTrack>
      </ColorSlider>
      <p>Current value: {color.toString('hsl')}</p>
    </div>
  );
}
```

## Disabled

A color area can be disabled using the `isDisabled` prop. This prevents the thumb from being focused or dragged.
It's up to you to style your color area to appear disabled accordingly.

```tsx example
<MyColorArea defaultValue="#ff0" isDisabled />
```

<details>
  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show CSS</summary>

```css
.react-aria-ColorArea {
  &[data-disabled] {
    background: gray !important;

    .react-aria-ColorThumb {
      background: gray !important;
    }
  }
}
```

</details>

## Labeling

By default, ColorArea provides an `aria-label` for the localized string "Color Picker",
which labels the visually hidden `<input>` elements for the two color channels. 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". If you provide your own `aria-label` or `aria-labelledby`, be sure to localize the string appropriately.

```tsx example
<div style={{display: 'flex', gap: 8, alignItems: 'end', flexWrap: 'wrap'}}>
  <MyColorArea
    /*- begin highlight -*/
    aria-label="Background color"
    /*- end highlight -*/
    defaultValue="hsl(0, 100%, 50%)"
    xChannel="saturation"
    yChannel="lightness" />
  <div>
    {/*- begin highlight -*/}
    <label id="hsl-aria-labelledby-id">Background color</label>
    {/*- end highlight -*/}
    <MyColorArea
      /*- begin highlight -*/
      aria-labelledby="hsl-aria-labelledby-id"
      /*- end highlight -*/
      defaultValue="hsl(0, 100%, 50%)"
      xChannel="saturation"
      yChannel="lightness" />
  </div>
</div>
```

### 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, along with a localized description of the selected color (e.g. "dark vibrant blue").

### Internationalization

In right-to-left languages, color areas should be mirrored.
Orientation of the gradient background, positioning of the thumb,
and dragging behavior is automatically mirrored by `ColorArea`.

## Props

### ColorArea

<PropTable component={docs.exports.ColorArea} links={docs.links} />

### ColorThumb

The `<ColorThumb>` component renders a draggable thumb with a preview of the selected color.

<details>
  <summary style={{fontWeight: 'bold'}}><ChevronRight size="S" /> Show props</summary>

<PropTable component={docs.exports.ColorThumb} links={docs.links} />

</details>

## Styling

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin `className` attribute which can be targeted using CSS selectors. These follow the `react-aria-ComponentName` naming convention.

```css
.react-aria-ColorArea {
  /* ... */
}
```

A custom `className` can also be specified on any component. This overrides the default `className` provided by React Aria with your own.

```jsx
<ColorArea className="my-color-area">
  {/* ... */}
</ColorArea>
```

In addition, some components support multiple UI states (e.g. focused, placeholder, readonly, etc.). React Aria components expose states using data attributes, which you can target in CSS selectors. For example:

```css
.react-aria-ColorThumb[data-dragging] {
  /* ... */
}

.react-aria-ColorThumb[data-focused] {
  /* ... */
}
```

The `className` and `style` props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like [Tailwind](https://tailwindcss.com/).

```jsx
<ColorThumb className={({isDragging}) => isDragging ? 'scale-150' : 'scale-100'} />
```

The states, selectors, and render props for each component used in a `ColorArea` are documented below.

### ColorArea

The `ColorArea` component can be targeted with the `.react-aria-ColorArea` CSS selector, or by overriding with a custom `className`. It supports the following states:

<StateTable properties={docs.exports.ColorAreaRenderProps.properties} />

### ColorThumb

The `ColorThumb` component can be targeted with the `.react-aria-ColorThumb` CSS selector, or by overriding with a custom `className`. It supports the following states:

<StateTable properties={docs.exports.ColorThumbRenderProps.properties} />

## Advanced customization

### Contexts

All React Aria Components export a corresponding context that can be used to send props to them from a parent element. This enables you to build your own compositional APIs similar to those found in React Aria Components itself. You can send any prop or ref via context that you could pass to the corresponding component. The local props and ref on the component are merged with the ones passed via context, with the local props taking precedence (following the rules documented in [mergeProps](mergeProps.html)).

<ContextTable components={['ColorArea']} docs={docs} />

This example shows a `ColorAreaDescription` component that accepts a color wheel in its children and renders a description element below it. It uses the [useId](useId.html) hook to generate a unique id for the description, and associates it with the color wheel via the `aria-describedby` attribute passed to the `ColorAreaContext` provider.

```tsx example
import {ColorAreaContext} from 'react-aria-components';
import {useId} from 'react-aria';

interface ColorAreaDescriptionProps {
  children?: React.ReactNode,
  description?: string
}

function ColorAreaDescription({children, description}: ColorAreaDescriptionProps) {
  let descriptionId = useId();
  return (
    <div>
      {/*- begin highlight -*/}
      <ColorAreaContext.Provider value={{'aria-describedby': descriptionId}}>
      {/*- end highlight -*/}
        {children}
      </ColorAreaContext.Provider>
      <small id={descriptionId}>{description}</small>
    </div>
  );
}

<ColorAreaDescription description="Choose a background color for your profile.">
  <MyColorArea />
</ColorAreaDescription>
```

### State

ColorArea provides a <TypeLink links={statelyDocs.links} type={statelyDocs.exports.ColorAreaState} /> object to its children via `ColorAreaStateContext`. This can be used to access and manipulate the color area's state.

### Hooks

If you need to customize things even further, such as accessing internal state or customizing DOM structure, you can drop down to the lower level Hook-based API. See [useColorArea](useColorArea.html) for more details.
