react-spectrum Documentation

An ActionBar is a companion component intended to facilitate bulk actions on selected items within a collection component. It consists of an ActionGroup, a clear button, and a count of selected items. It accepts a list of
elements as children, each with a key prop. Alternatively, a function that returns Item elements is also supported as seen below. See the collection components
docs for more details about this API. These Item elements are used to populate the buttons in the ActionBar, and follows the ActionGroup content guidelines for customization and labeling.

import type {Selection} from '@adobe/react-spectrum';

function Example() {
  let barItems = [
    {key: 'edit', label: 'Edit'},
    {key: 'copy', label: 'Copy'},
    {key: 'delete', label: 'Delete'}
  ];

  let [selectedKeys, setSelectedKeys] = React.useState<Selection>(new Set(['photoshop']));

  return (
    <ActionBarContainer height={300} maxWidth="size-6000">
      <ListView aria-label="ListView with action bar" selectionMode="multiple" selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys}>
        <Item key="photoshop">Adobe Photoshop</Item>
        <Item key="illustrator">Adobe Illustrator</Item>
        <Item key="xd">Adobe XD</Item>
      </ListView>
      <ActionBar
        items={barItems}
        selectedItemCount={selectedKeys === 'all' ? 'all' : selectedKeys.size}
        onAction={(key) => alert(`Performing ${key} action...`)}
        onClearSelection={() => setSelectedKeys(new Set())}
        isEmphasized>
        {item => (
          <Item key={item.key}>
            {item.label}
          </Item>
        )}
      </ActionBar>
    </ActionBarContainer>
  );
}

<Example />

Accessibility Copy Section

The contents of the ActionBar should follow the same accessibility guidelines as ActionGroup's items, see the ActionGroup docs for more details.

Internationalization Copy Section

To internationalize an ActionBar, the content provided to all child items should be localized. A localized string for the selection count and clear button aria-label will be provided
automatically. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the ActionBar is automatically flipped.

Events Copy Chapter

Use the onClearSelection prop as a callback to handle when the clear button in the ActionBar is pressed. Additionally, the onAction prop can be used as a callback for when the user
presses any of the buttons in the ActionBar. The key from the pressed `` will be passed to the callback.

The following example clears row selection within the TableView when the clear button is pressed and alerts the user as to what
action is being taken on the selected rows when the buttons are pressed.

/* Detailed source-code truncated for AI context efficiency. */

Props Copy Chapter

ActionBarContainer props Copy Section

ActionBar props Copy Section

Visual options Copy Chapter

isEmphasized Copy Section

isEmphasized should be applied to the ActionBar when it should call attention, such as when floating in a TableView. It should be omitted if the ActionBar should blend in
with the rest of the UI, directing a user’s focus to elsewhere in a view.

import type {Selection} from '@adobe/react-spectrum';

function Example({isEmphasized}: {isEmphasized?: boolean}) {
  let [selectedKeys, setSelectedKeys] = React.useState<Selection>(new Set(['photoshop']));

  return (
    <ActionBarContainer height={300} width="size-5000">
      <ListView aria-label="ListView with action bar" selectionMode="multiple" selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys}>
        <Item key="photoshop">Adobe Photoshop</Item>
        <Item key="illustrator">Adobe Illustrator</Item>
        <Item key="xd">Adobe XD</Item>
      </ListView>
      <ActionBar
        /*- begin highlight -*/
        isEmphasized={isEmphasized}
        /*- end highlight -*/
        selectedItemCount={selectedKeys === 'all' ? 'all' : selectedKeys.size}
        onAction={(key) => alert(`Performing ${key} action...`)}
        onClearSelection={() => setSelectedKeys(new Set())}>
        <Item key="edit">
          <Edit />
          <Text>Edit</Text>
        </Item>
        <Item key="copy">
          <Copy />
          <Text>Copy</Text>
        </Item>
        <Item key="delete">
          <Delete />
          <Text>Delete</Text>
        </Item>
      </ActionBar>
    </ActionBarContainer>
  );
}

<Flex direction="row" gap="size-200" wrap>
  <Example />
  <Example isEmphasized />
</Flex>

isDisabled Copy Section

To disable individual items, a list of disabledKeys can be provided.

import type {Selection} from '@adobe/react-spectrum';

function Example() {
  let [selectedKeys, setSelectedKeys] = React.useState<Selection>(new Set(['photoshop']));

  return (
    <ActionBarContainer height={300} width="size-5000">
      <ListView aria-label="ListView with action bar" selectionMode="multiple" selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys}>
        <Item key="photoshop">Adobe Photoshop</Item>
        <Item key="illustrator">Adobe Illustrator</Item>
        <Item key="xd">Adobe XD</Item>
      </ListView>
      <ActionBar
        /*- begin highlight -*/
        disabledKeys={['edit']}
        /*- end highlight -*/
        isEmphasized={true}
        selectedItemCount={selectedKeys === 'all' ? 'all' : selectedKeys.size}
        onAction={(key) => alert(`Performing ${key} action...`)}
        onClearSelection={() => setSelectedKeys(new Set())}>
        <Item key="edit">
          <Edit />
          <Text>Edit</Text>
        </Item>
        <Item key="copy">
          <Copy />
          <Text>Copy</Text>
        </Item>
        <Item key="delete">
          <Delete />
          <Text>Delete</Text>
        </Item>
      </ActionBar>
    </ActionBarContainer>
  );
}

<Example />

Packages @Adobe React Spectrum Docs Actiongroup ActionGroup (`packages/@adobe/react-spectrum/docs/actiongroup/ActionGroup.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/actiongroup';
import collectionsDocs from 'docs:@react-stately/collections';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/actiongroup/package.json';

import {ActionGroup, Item} from '@react-spectrum/actiongroup';
import Brush from '@spectrum-icons/workflow/Brush';
import RegionSelect from '@spectrum-icons/workflow/RegionSelect';
import Select from '@spectrum-icons/workflow/Select';
import {Flex} from '@react-spectrum/layout';
import {View} from '@react-spectrum/view';
import ViewList from '@spectrum-icons/workflow/ViewList';
import ViewGrid from '@spectrum-icons/workflow/ViewGrid';
import ViewCard from '@spectrum-icons/workflow/ViewCard';
import Move from '@spectrum-icons/workflow/Move';
import Duplicate from '@spectrum-icons/workflow/Duplicate';
import TagBold from '@spectrum-icons/workflow/TagBold';
import TagItalic from '@spectrum-icons/workflow/TagItalic';
import TagUnderline from '@spectrum-icons/workflow/TagUnderline';
import TextStrikethrough from '@spectrum-icons/workflow/TextStrikethrough';
import TextAlignCenter from '@spectrum-icons/workflow/TextAlignCenter';
import TextAlignJustify from '@spectrum-icons/workflow/TextAlignJustify';
import TextAlignLeft from '@spectrum-icons/workflow/TextAlignLeft';
import TextAlignRight from '@spectrum-icons/workflow/TextAlignRight';

category: Buttons keywords: [toolbar, actiongroup, collections] Copy Chapter

ActionGroup

{docs.exports.ActionGroup.description}

<HeaderInfo
packageData={packageData}
componentNames={['ActionGroup', 'Item']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/action-group/'}
]}
since="3.0.0" />

Example Copy Chapter

function Example() {
  let [action, setAction] = React.useState(null);

  return (
    <>
      <ActionGroup onAction={setAction}>
        <Item key="add">Add</Item>
        <Item key="delete">Delete</Item>
        <Item key="edit">Edit</Item>
      </ActionGroup>
      <p>Action: {action}</p>
    </>
  );
}

Content Copy Chapter

ActionGroups accept a list of elements as children, each with a key prop. Alternatively, a function that returns Item elements is also supported. See the collection components docs for more details about this API.

const items = [
  {label: 'React', name: 'React'},
  {label: 'Add', name: 'Add'},
  {label: 'Delete', name: 'Delete'}
];

<ActionGroup items={items}>
  {item => <Item key={item.name}>{item.label}</Item>}
</ActionGroup>

Icons Copy Section

Icons can be added to ActionGroup items by wrapping the label in a Text element, and adding the icon as a sibling.

import Draw from '@spectrum-icons/workflow/Draw';
import Copy from '@spectrum-icons/workflow/Copy';
import Delete from '@spectrum-icons/workflow/Delete';
import {Text} from '@react-spectrum/text';

<ActionGroup>
  <Item key="edit">
    <Draw />
    <Text>Edit</Text>
  </Item>
  <Item key="copy">
    <Copy />
    <Text>Copy</Text>
  </Item>
  <Item key="delete">
    <Delete />
    <Text>Delete</Text>
  </Item>
</ActionGroup>

You can also hide the label text within the buttons using the buttonLabelBehavior prop. When set to "hide", the label is
hidden and automatically shown in a tooltip on hover.

<ActionGroup buttonLabelBehavior="hide">
  <Item key="edit">
    <Draw />
    <Text>Edit</Text>
  </Item>
  <Item key="copy">
    <Copy />
    <Text>Copy</Text>
  </Item>
  <Item key="delete">
    <Delete />
    <Text>Delete</Text>
  </Item>
</ActionGroup>

Accessibility Copy Section

Icon only ActionGroups should usually include a tooltip to describe the button via the buttonLabelBehavior prop as described above. This also automatically handles
labeling the button for assistive technology users.

In rare cases where no tooltip is desired, an alternative text label must be provided to identify the control for accessibility.
This should be added using the aria-label prop to each Item.

<ActionGroup>
  <Item key="brush" aria-label="Brush"><Brush /></Item>
  <Item key="select" aria-label="Select"><Select /></Item>
  <Item key="regionSelect" aria-label="Select Region"><RegionSelect /></Item>
</ActionGroup>

Internationalization Copy Section

In order to internationalize an ActionGroup, the content provided to all child items should be localized.

Selection Copy Chapter

ActionGroup supports multiple selection modes. By default, selection is disabled, however this can be changed using the selectionMode prop.
Use defaultSelectedKeys to provide a default set of selected items (uncontrolled) and selectedKeys to set the selected items (controlled). The value of the selected keys must match the key prop of the items.
See the react-stately Selection docs for caveats regarding selection prop typing.

<ActionGroup selectionMode="single" defaultSelectedKeys={['list']}>
  <Item key="grid">Grid view</Item>
  <Item key="list">List view</Item>
  <Item key="gallery">Gallery view</Item>
</ActionGroup>

The selectedKeys prop can be used to make the selected state controlled.

import type {Selection} from '@adobe/react-spectrum';

function Example() {
  let [selected, setSelected] = React.useState<Selection>(new Set(['list']));

  return (
    <>
      <ActionGroup selectionMode="single" selectedKeys={selected} onSelectionChange={setSelected}>
        <Item key="grid">Grid view</Item>
        <Item key="list">List view</Item>
        <Item key="gallery">Gallery view</Item>
      </ActionGroup>
      <p>Current selection (controlled): {[...selected]}</p>
    </>
  );
}

Set selectionMode prop to multiple to allow more than one selection.

function Example() {
  let [selected, setSelected] = React.useState<Selection>(new Set(['list']));

  return (
    <>
      <ActionGroup selectionMode="multiple" selectedKeys={selected} onSelectionChange={setSelected}>
        <Item key="grid">Grid view</Item>
        <Item key="list">List view</Item>
        <Item key="gallery">Gallery view</Item>
      </ActionGroup>
      <p>Current selections (controlled): {[...selected].join(', ')}</p>
    </>
  );
}

Events Copy Chapter

Use the onSelectionChange prop as a callback to handle press events on items when selectionMode is either single or multiple.
The key prop from the selected item will be passed into the callback.

To continue to capturing actions when selectionMode is none, utilize the onAction prop.

import type {Key} from '@adobe/react-spectrum';

function Example() {
  let [actionKey, setActionKey] = React.useState<Key>('');
  return (
    <>
      <ActionGroup onAction={setActionKey}>
        <Item key="add">Add</Item>
        <Item key="delete">Delete</Item>
        <Item key="edit">Edit</Item>
      </ActionGroup>
      <p>Action: {actionKey}</p>
    </>
  );
}

Collapsing behavior Copy Chapter

By default, ActionGroup items wrap to form a new line when horizontal space is limited. However, this can cause content to shift below the
ActionGroup. If the ActionGroup should always appear in a single line, the overflowMode prop can be set to collapse. In this mode, when
horizontal space is limited, the ActionGroup will collapse into a menu. The exact behavior depends on the selectionMode.

Non-selectable Copy Section

When selection is not enabled, ActionGroup displays as many items as possible and collapses the remaining items into a more actions menu.

<ActionGroup overflowMode="collapse" maxWidth={250}>
  <Item key="edit">
    <Draw />
    <Text>Edit</Text>
  </Item>
  <Item key="copy">
    <Copy />
    <Text>Copy</Text>
  </Item>
  <Item key="delete">
    <Delete />
    <Text>Delete</Text>
  </Item>
  <Item key="move">
    <Move />
    <Text>Move</Text>
  </Item>
  <Item key="duplicate">
    <Duplicate />
    <Text>Duplicate</Text>
  </Item>
</ActionGroup>

Selection Copy Section

When selection is enabled, ActionGroup collapses all items into a menu together when space is limited. The menu button indicates when one of
the options within it is selected by showing a highlighted state. A summaryIcon should be specified to visually communicate the purpose of
the ActionGroup when collapsed, and an aria-label should be provided to describe the ActionGroup to assistive technology.

This example shows a multi-selectable ActionGroup that can be used to select text styles. When space is limited, it collapses into a dropdown
menu, and displays the TextStyle icon passed to the summaryIcon prop.

import TextStyle from '@spectrum-icons/workflow/TextStyle';

<ActionGroup
  aria-label="Text style"
  overflowMode="collapse"
  selectionMode="multiple"
  isEmphasized
  summaryIcon={<TextStyle />}
  maxWidth={100}>
  <Item key="bold">
    <TagBold />
    <Text>Bold</Text>
  </Item>
  <Item key="italic">
    <TagItalic />
    <Text>Italic</Text>
  </Item>
  <Item key="underline">
    <TagUnderline />
    <Text>Underline</Text>
  </Item>
  <Item key="strike">
    <TextStrikethrough />
    <Text>Strikethrough</Text>
  </Item>
</ActionGroup>

Single selection Copy Section

A special case where a summaryIcon is not needed is a single selectable ActionGroup (selectionMode="single") which enforces that an item
is always selected (disallowEmptySelection). In this case, the selected item is displayed inside the menu button when collapsed.

<ActionGroup
  aria-label="Text alignment"
  overflowMode="collapse"
  selectionMode="single"
  defaultSelectedKeys={['left']}
  disallowEmptySelection
  buttonLabelBehavior="hide"
  isEmphasized
  maxWidth={100}>
  <Item key="left">
    <TextAlignLeft />
    <Text>Align Left</Text>
  </Item>
  <Item key="center">
    <TextAlignCenter />
    <Text>Align Center</Text>
  </Item>
  <Item key="right">
    <TextAlignRight />
    <Text>Align Right</Text>
  </Item>
  <Item key="justify">
    <TextAlignJustify />
    <Text>Justify</Text>
  </Item>
</ActionGroup>

Collapsing button labels Copy Section

In addition to collapsing items that don't fit into a menu, the button labels can also be automatically hidden when space is limited.
This keeps more buttons visible at a time before needing to collapse into a menu. This behavior can be enabled by setting the
buttonLabelBehavior prop to "collapse". The labels will be automatically shown in tooltips when collapsed.

<ActionGroup overflowMode="collapse" buttonLabelBehavior="collapse" maxWidth={180}>
  <Item key="edit">
    <Draw />
    <Text>Edit</Text>
  </Item>
  <Item key="copy">
    <Copy />
    <Text>Copy</Text>
  </Item>
  <Item key="delete">
    <Delete />
    <Text>Delete</Text>
  </Item>
  <Item key="move">
    <Move />
    <Text>Move</Text>
  </Item>
  <Item key="duplicate">
    <Duplicate />
    <Text>Duplicate</Text>
  </Item>
</ActionGroup>

Vertical collapsing behavior Copy Section

Non-selectable vertical ActionGroups also support collapsing when the height is too small to fit all of the buttons.
The behavior is the same as for horizontal ActionGroups, except for the positioning of the tooltips and menu.

Vertical ActionGroups with selection do not currently support collapsing. When selection is enabled, we recommend placing
the ActionGroup in a scrollable container so that the user can access all items.

<ActionGroup overflowMode="collapse" orientation="vertical" buttonLabelBehavior="hide" maxHeight={150}>
  <Item key="edit">
    <Draw />
    <Text>Edit</Text>
  </Item>
  <Item key="copy">
    <Copy />
    <Text>Copy</Text>
  </Item>
  <Item key="delete">
    <Delete />
    <Text>Delete</Text>
  </Item>
  <Item key="move">
    <Move />
    <Text>Move</Text>
  </Item>
  <Item key="duplicate">
    <Duplicate />
    <Text>Duplicate</Text>
  </Item>
</ActionGroup>

Props Copy Chapter

Visual options Copy Chapter

Quiet Copy Section

<ActionGroup isQuiet>
  <Item key="add">Add</Item>
  <Item key="delete">Delete</Item>
  <Item key="edit">Edit</Item>
</ActionGroup>

Emphasized Copy Section

The additional styling provided by the isEmphasized prop is only applied when items are selected.

<ActionGroup
  isEmphasized
  selectionMode="single"
  defaultSelectedKeys={['list']}>
  <Item key="grid">Grid view</Item>
  <Item key="list">List view</Item>
  <Item key="gallery">Gallery view</Item>
</ActionGroup>

Static color Copy Section

The staticColor prop can be used when the ActionGroup is displayed over a color background. When selected, the icon and text in each
button automatically take on the color of the background. You are responsible for choosing the static color variant that ensures the
text meets an accessible contrast ratio
with the background.

<Flex wrap gap="size-250">
  <View backgroundColor="static-blue-700" padding="size-500">
    <ActionGroup staticColor="white">
      <Item key="edit">
        <Draw />
        <Text>Edit</Text>
      </Item>
      <Item key="copy">
        <Copy />
        <Text>Copy</Text>
      </Item>
      <Item key="delete">
        <Delete />
        <Text>Delete</Text>
      </Item>
    </ActionGroup>
  </View>
  <View backgroundColor="static-yellow-400" padding="size-500">
    <ActionGroup
      staticColor="black"
      isQuiet
      buttonLabelBehavior="hide"
      selectionMode="single"
      disallowEmptySelection
      defaultSelectedKeys={['list']}>
      <Item key="list">
        <ViewList />
        <Text>List view</Text>
      </Item>
      <Item key="grid">
        <ViewGrid />
        <Text>Grid view</Text>
      </Item>
      <Item key="gallery">
        <ViewCard />
        <Text>Gallery view</Text>
      </Item>
    </ActionGroup>
  </View>
</Flex>

Disabled Copy Section

To disable the entire ActionGroup, use the isDisabled prop on the root.

<ActionGroup isDisabled>
  <Item key="add">Add</Item>
  <Item key="delete">Delete</Item>
  <Item key="edit">Edit</Item>
</ActionGroup>

To disable individual items, a list of disabledKeys can be provided.

<ActionGroup disabledKeys={['add', 'delete']}>
  <Item key="add">Add</Item>
  <Item key="delete">Delete</Item>
  <Item key="edit">Edit</Item>
</ActionGroup>

Orientation Copy Section

Using the orientation prop with value vertical changes the alignment of the items to follow the y-axis.

<ActionGroup orientation="vertical">
  <Item key="brush" aria-label="Brush"><Brush /></Item>
  <Item key="select" aria-label="Select"><Select /></Item>
  <Item key="regionSelect" aria-label="Select Region"><RegionSelect /></Item>
</ActionGroup>

Density Copy Section

Using the density prop with value compact changes the margins between the buttons.
In the default case, this merges the borders of neighboring ActionButtons. In the
quiet case, it just reduces the margin size between the buttons.

<ActionGroup density="compact">
  <Item key="brush" aria-label="Brush"><Brush /></Item>
  <Item key="select" aria-label="Select"><Select /></Item>
  <Item key="regionSelect" aria-label="Select Region"><RegionSelect /></Item>
</ActionGroup>

<ActionGroup isQuiet density="compact">
  <Item key="brush" aria-label="Brush"><Brush /></Item>
  <Item key="select" aria-label="Select"><Select /></Item>
  <Item key="regionSelect" aria-label="Select Region"><RegionSelect /></Item>
</ActionGroup>

Justified Copy Section

The isJustified prop will divide all available horizontal space evenly among the buttons.

<Flex width="size-2000" direction="column">
  <ActionGroup isJustified>
    <Item key="brush" aria-label="Brush"><Brush /></Item>
    <Item key="select" aria-label="Select"><Select /></Item>
    <Item key="regionSelect" aria-label="Select Region"><RegionSelect /></Item>
  </ActionGroup>
</Flex>

Packages @Adobe React Spectrum Docs Autocomplete SearchAutocomplete (`packages/@adobe/react-spectrum/docs/autocomplete/SearchAutocomplete.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/autocomplete';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/autocomplete/package.json';

import {SearchAutocomplete, Section, Item} from '@react-spectrum/autocomplete';
import {useFilter} from '@react-aria/i18n';
import Email from '@spectrum-icons/workflow/Email';
import Document from '@spectrum-icons/workflow/Document';
import WebPages from '@spectrum-icons/workflow/WebPages';
import SocialNetwork from '@spectrum-icons/workflow/SocialNetwork';
import ShoppingCart from '@spectrum-icons/workflow/ShoppingCart';
import Folder from '@spectrum-icons/workflow/Folder';
import {Text} from '@react-spectrum/text';
import {Avatar} from "@react-spectrum/avatar";

category: Pickers keywords: [search field, input] after_version: 3.0.0 Copy Chapter

SearchAutocomplete

{docs.exports.SearchAutocomplete.description}

<HeaderInfo
packageData={packageData}
componentNames={['SearchAutocomplete', 'Section', 'Item']} />

Example Copy Chapter

<SearchAutocomplete label="Search with Autocomplete">
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Content Copy Chapter

SearchAutocomplete follows the Collection Components API, accepting both static and dynamic collections.
Similar to ComboBox, SearchAutocomplete accepts `` elements as children, each with a key prop. Basic usage of SearchAutocomplete, seen in the example above, shows multiple options populated with a string.
Static collections, as in this example, can be used when the full list of options is known ahead of time.

Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time.
Providing the data in this way allows SearchAutocomplete to automatically cache the rendering of each item, which dramatically improves performance.

As seen below, an iterable list of options is passed to the SearchAutocomplete using the defaultItems prop.

function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];

  return (
    <SearchAutocomplete
      label="Search engineering majors"
      defaultItems={options}>
      {item => <Item>{item.name}</Item>}
    </SearchAutocomplete>
  );
}

Alternatively, passing your list of options to SearchAutocomplete's items prop will cause the list of items to be controlled, useful for when you want to provide your own
filtering logic. See the Custom Filtering section for more detail.

Internationalization Copy Section

To internationalize a SearchAutocomplete, a localized string should be passed to the children of each Item.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the SearchAutocomplete is automatically flipped.

Labeling Copy Chapter

SearchAutocomplete can be labeled using the label prop. If the SearchAutocomplete is a required field, the isRequired and necessityIndicator props can be used to show a required state.

<SearchAutocomplete label="Favorite Animal" isRequired necessityIndicator="icon">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete label="Favorite Animal" isRequired necessityIndicator="label">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete label="Favorite Animal" necessityIndicator="label">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Accessibility Copy Section

If a visible label isn't specified, an aria-label must be provided to the SearchAutocomplete for
accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using
the id of the labeling element instead.

Internationalization Copy Section

In order to internationalize a SearchAutocomplete, a localized string should be passed to the label or aria-label prop.
When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Links Copy Chapter

By default, interacting with an item in a SearchAutocomplete updates the input value. Alternatively, items may be links to another page or website. This can be achieved by passing the href prop to the `` component. Interacting with link items navigates to the provided URL and does not update the input value.

<SearchAutocomplete label="Tech company websites">
  <Item href="https://adobe.com/" target="_blank">Adobe</Item>
  <Item href="https://apple.com/" target="_blank">Apple</Item>
  <Item href="https://google.com/" target="_blank">Google</Item>
  <Item href="https://microsoft.com/" target="_blank">Microsoft</Item>
</SearchAutocomplete>

Client side routing Copy Section

The `` component works with frameworks and client side routers like Next.js and React Router. As with other React Spectrum components that support links, this works via the Provider component at the root of your app. See the client side routing guide to learn how to set this up.

Sections Copy Chapter

SearchAutocomplete supports sections in order to group options. Sections can be used by wrapping groups of items in a Section element. Each Section takes a title and key prop.

Static items Copy Section

<SearchAutocomplete label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item key="Apple">Apple</Item>
    <Item key="Banana">Banana</Item>
    <Item key="Orange">Orange</Item>
    <Item key="Honeydew">Honeydew</Item>
    <Item key="Grapes">Grapes</Item>
    <Item key="Watermelon">Watermelon</Item>
    <Item key="Cantaloupe">Cantaloupe</Item>
    <Item key="Pear">Pear</Item>
  </Section>
  <Section title="Vegetable">
    <Item key="Cabbage">Cabbage</Item>
    <Item key="Broccoli">Broccoli</Item>
    <Item key="Carrots">Carrots</Item>
    <Item key="Lettuce">Lettuce</Item>
    <Item key="Spinach">Spinach</Item>
    <Item key="Bok Choy">Bok Choy</Item>
    <Item key="Cauliflower">Cauliflower</Item>
    <Item key="Potatoes">Potatoes</Item>
  </Section>
</SearchAutocomplete>

Dynamic items Copy Section

Sections used with dynamic items are populated from a hierarchical data structure. Please note that Section takes an array of data using the items prop only.

function Example() {
  let options = [
    {name: 'Fruit', children: [
      {name: 'Apple'},
      {name: 'Banana'},
      {name: 'Orange'},
      {name: 'Honeydew'},
      {name: 'Grapes'},
      {name: 'Watermelon'},
      {name: 'Cantaloupe'},
      {name: 'Pear'}
    ]},
    {name: 'Vegetable', children: [
      {name: 'Cabbage'},
      {name: 'Broccoli'},
      {name: 'Carrots'},
      {name: 'Lettuce'},
      {name: 'Spinach'},
      {name: 'Bok Choy'},
      {name: 'Cauliflower'},
      {name: 'Potatoes'}
    ]}
  ];

  return (
    <SearchAutocomplete label="Preferred fruit or vegetable" defaultItems={options}>
      {item => (
        <Section key={item.name} items={item.children} title={item.name}>
          {item => <Item key={item.name}>{item.name}</Item>}
        </Section>
      )}
    </SearchAutocomplete>
  );
}

Complex items Copy Chapter

Items within SearchAutocomplete also allow for additional content used to better communicate options. Icons, avatars, and descriptions can be added to the children of Item as shown in the example below.
If a description is added, the prop slot="description" must be used to distinguish the different <Text> elements.
See Icon's labeling section and Avatar's accessibility section for more information on how to label these elements.

<SearchAutocomplete label="Search apps">
  <Section title="Productivity">
    <Item textValue="Mail">
      <Email size="S" />
      <Text>Mail</Text>
      <Text slot="description">Send and receive emails</Text>
    </Item>
    <Item textValue="File Explorer">
      <Folder size="S" />
      <Text>File Explorer</Text>
      <Text slot="description">Navigate directories and open files</Text>
    </Item>
    <Item textValue="Document Editor">
      <Document size="S" />
      <Text>Document Editor</Text>
      <Text slot="description">Edit documents</Text>
    </Item>
  </Section>
  <Section title="Internet">
    <Item textValue="Web Browser">
      <WebPages size="S" />
      <Text>Web Browser</Text>
      <Text slot="description">Browse the internet</Text>
    </Item>
    <Item textValue="Social Media">
      <SocialNetwork size="S" />
      <Text>Social Media</Text>
      <Text slot="description">Connect with friends</Text>
    </Item>
    <Item textValue="Shopping">
      <ShoppingCart size="S" />
      <Text>Shopping</Text>
      <Text slot="description">Shop online</Text>
    </Item>
  </Section>
</SearchAutocomplete>

With avatars Copy Section

<SearchAutocomplete label="Search users">
  <Item textValue="User 1">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 1</Text>
  </Item>
  <Item textValue="User 2">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 2</Text>
  </Item>
  <Item textValue="User 3">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 3</Text>
  </Item>
  <Item textValue="User 4">
    <Avatar src="https://i.imgur.com/kJOwAdv.png" />
    <Text>User 4</Text>
  </Item>
</SearchAutocomplete>

Asynchronous loading Copy Chapter

SearchAutocomplete supports loading data asynchronously, and will display a progress circle reflecting the current load state,
set by the loadingState prop. It also supports infinite scrolling to load more data on demand as the user scrolls, via the onLoadMore prop.

This example uses the useAsyncList hook to handle loading the data. See the docs for more information.

import {useAsyncList} from '@react-stately/data';

interface Character {
  name: string
}

function AsyncLoadingExample() {
  let list = useAsyncList<Character>({
    async load({signal, cursor, filterText}) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      // If no cursor is available, then we're loading the first page,
      // filtering the results returned via a query string that
      // mirrors the SearchAutocomplete input text.
      // Otherwise, the cursor is the next URL to load,
      // as returned from the previous page.
      let res = await fetch(cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, {signal});
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <SearchAutocomplete
      label="Star Wars Character Lookup"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      loadingState={list.loadingState}
      onLoadMore={list.loadMore}>
      {item => <Item key={item.name}>{item.name}</Item>}
    </SearchAutocomplete>
  );
}

Validation Copy Chapter

SearchAutocomplete supports the isRequired prop to ensure the user enters a value, as well as custom client and server-side validation. It can also be integrated with other form libraries. See the Forms guide to learn more.

When the Form component has the validationBehavior="native" prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the search field or submits the form.

import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  {/*- begin highlight -*/}
  <SearchAutocomplete label="Favorite animal" name="animal" isRequired>
  {/*- end highlight -*/}
    <Item>Aardvark</Item>
    <Item>Cat</Item>
    <Item>Dog</Item>
    <Item>Kangaroo</Item>
    <Item>Panda</Item>
    <Item>Snake</Item>
  </SearchAutocomplete>
  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>

By default, SearchAutocomplete displays default validation messages provided by the browser. See Customizing error messages in the Forms guide to learn how to provide your own custom errors.

Custom Filtering Copy Chapter

By default, SearchAutocomplete uses a string "contains" filtering strategy when deciding what items to display in the dropdown menu. This filtering strategy can be overwritten
by filtering the list of items yourself and passing the filtered list to the SearchAutocomplete via the items prop.

The example below uses a string "startsWith" filter function obtained from the useFilter hook to display items that start with the SearchAutocomplete's current input
value only. By using the menuTrigger returned by onOpenChange, it also handles displaying the entire option list regardless of the current filter value when the SearchAutocomplete menu is
opened via the trigger button or arrow keys. menuTrigger tells you if the menu was opened manually by the user ("manual"), by focusing the SearchAutocomplete ("focus"), or by
changes in the input field ("input"), allowing you to make updates to other controlled aspects of your SearchAutocomplete accordingly.

function Example() {
  let options = [
    {id: 1, email: '[email protected]'},
    {id: 2, email: '[email protected]'},
    {id: 3, email: '[email protected]'},
    {id: 4, email: '[email protected]'},
    {id: 5, email: '[email protected]'},
    {id: 6, email: '[email protected]'},
    {id: 7, email: '[email protected]'},
    {id: 8, email: '[email protected]'},
    {id: 9, email: '[email protected]'}
  ];

  let [showAll, setShowAll] = React.useState(false);
  let [filterValue, setFilterValue] = React.useState('');
  let {startsWith} = useFilter({sensitivity: 'base'});
  let filteredItems = React.useMemo(() => options.filter(item => startsWith(item.email, filterValue)), [options, filterValue]);

  return (
    <SearchAutocomplete
      onOpenChange={(isOpen, menuTrigger) => {
        // Show all items if menu is opened manually
        // i.e. by the arrow keys or trigger button
        if (menuTrigger === 'manual' && isOpen) {
          setShowAll(true);
        }
      }}
      width="size-3000"
      label="Search Email Addresses"
      items={showAll ? options : filteredItems}
      inputValue={filterValue}
      onInputChange={(value) => {
        setShowAll(false);
        setFilterValue(value);
      }}>
      {item => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}

Trigger options Copy Chapter

By default, the SearchAutocomplete's menu is opened when the user types into the input field ("input"). There are two other supported modes: one where the menu opens when the SearchAutocomplete is focused ("focus") and
the other where the menu only opens when the user clicks or taps on the SearchAutocomplete's field button ("manual"). These can be set by providing "focus" or "manual" to the menuTrigger prop.
Guidelines on when to use a specific mode can be found here. Note that the mobile SearchAutocomplete experience requires the end user to press the SearchAutocomplete button
to open the tray regardless of the menuTrigger setting.

<SearchAutocomplete label="Favorite Animal" menuTrigger="focus">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

<SearchAutocomplete label="Favorite Animal" menuTrigger="manual">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Props Copy Chapter

Visual options Copy Chapter

Label alignment and position Copy Section

By default, the label is positioned above the SearchAutocomplete. The labelPosition prop can be used to position the label to the side.
The labelAlign prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the left most edge of the SearchAutocomplete and "end" refers to the right most edge.
For right-to-left (RTL) languages, this is flipped.

<SearchAutocomplete label="Favorite Animal" labelPosition="side" labelAlign="end">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Quiet Copy Section

<SearchAutocomplete label="Favorite Animal" isQuiet>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Disabled Copy Section

<SearchAutocomplete label="Favorite Animal" isDisabled>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Read only Copy Section

<SearchAutocomplete label="Search Animals" isReadOnly>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Custom widths Copy Section

<SearchAutocomplete label="Favorite Animal" width="size-6000" maxWidth="100%">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Menu direction Copy Section

<SearchAutocomplete label="Favorite Animal" direction="top">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Testing Copy Chapter

The SearchAutocomplete features an overlay that transitions in and out of the page as it is opened and closed. Depending on
your device configuration, this overlay may render as a tray or a dropdown and the trigger itself may render as a button or a input. Additionally,
the SearchAutocomplete features automatic virtualization and may need specific mocks in a test environment to enable said virtualization properly.
Please see the following sections in the testing docs for more information on how to handle these
behaviors in your test suite.

Timers

Desktop vs Mobile

Virtualized Components

Long press

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.

Packages @Adobe React Spectrum Docs Avatar Avatar (`packages/@adobe/react-spectrum/docs/avatar/Avatar.mdx`) Copy Section

{/* Copyright 2022 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-spectrum/avatar';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/avatar/package.json';

import {Avatar} from '@react-spectrum/avatar';
import {Flex} from '@react-spectrum/layout';

category: Content keywords: [avatar] Copy Chapter

Avatar

{docs.exports.Avatar.description}

<HeaderInfo
packageData={packageData}
componentNames={['Avatar']}
sourceData={[{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/avatar/'}]}
since="3.26.0" />

Example Copy Chapter

<Avatar src="https://i.imgur.com/kJOwAdv.png" alt="default Adobe avatar" />

Content Copy Chapter

The Avatar component is a thumbnail representation of an entity, such as a user or an organization. They accept a src attribute defining the image URL, and an alt attribute for an accessible description.

Accessibility Copy Section

By default, avatars are decorative and have an empty alt attribute. Standalone avatars with no surrounding context must have a custom alt prop defined for accessibility.

Internationalization Copy Section

To internationalize an Avatar, a localized string should be passed to the alt prop.

Props Copy Chapter

Visual options Copy Chapter

Disabled Copy Section

View guidelines

<Avatar src="https://i.imgur.com/kJOwAdv.png" alt="default Adobe avatar" isDisabled />

Size Copy Section

View guidelines

Sizes can either be one of the predefined avatar size variables, or a custom size in pixels.

<Flex gap="size-100" wrap>
  {[50, 75, 100, 200, 300, 400, 500, 600, 700].map(size => (
    <Avatar key={size} src="https://i.imgur.com/kJOwAdv.png" alt="default Adobe avatar" size={`avatar-size-${size}`} />
  ))}
  <Avatar src="https://i.imgur.com/kJOwAdv.png" alt="avatar with custom size" size={50} />
</Flex>

Packages @Adobe React Spectrum Docs Badge Badge (`packages/@adobe/react-spectrum/docs/badge/Badge.mdx`) Copy Section

{/* Copyright 2022 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-spectrum/badge';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/badge/package.json';

import {Badge} from '@react-spectrum/badge';

category: Status keywords: [badge] Copy Chapter

Badge

{docs.exports.Badge.description}

<HeaderInfo
packageData={packageData}
componentNames={['Badge']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/badge/'}
]}
since="3.22.0" />

Example Copy Chapter

<Badge variant="positive">Licensed</Badge>

Content Copy Chapter

Badges can have a label, an icon, or both. An icon is provided by passing an icon component as a child to the Badge.
A visible label can be provided by passing a string or a Text component as a child, depending on whether the Badge has an accompanying icon.

import {Text} from '@react-spectrum/text';
import CheckmarkCircle from '@spectrum-icons/workflow/CheckmarkCircle';

<Badge variant="positive">
  <CheckmarkCircle aria-label="Done" />
  <Text>Icon + Label</Text>
</Badge>

Accessibility Copy Section

If a visible label isn't specified, an aria-label must be provided to the icon for accessibility.

Internationalization Copy Section

To internationalize a Badge, a localized string should be set as the child content of the Badge.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the Badge is automatically flipped.

Props Copy Chapter

Visual options Copy Chapter

Variant Copy Section

View guidelines

When badges have a semantic meaning, they should use semantic colors.
Use the appropriate color to indicate status as follows.

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

<Flex direction="column" gap={8}>
  <Badge variant="positive">Green: Approved, Complete, Success, New, Purchased, Licensed</Badge>
  <Badge variant="info">Blue: Active, In Use, Live, Published</Badge>
  <Badge variant="negative">Red: Error, Alert, Rejected, Failed</Badge>
  <Badge variant="neutral">Gray: Archived, Deleted, Paused, Draft, Not Started, Ended</Badge>
</Flex>

When badges are used to color code categories, they use label colors. The ideal usage for these is when there
are 8 or fewer categories being color coded.

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

<Flex direction="column" gap={8}>
  <Badge variant="seafoam">Seafoam</Badge>
  <Badge variant="indigo">Indigo</Badge>
  <Badge variant="purple">Purple</Badge>
  <Badge variant="fuchsia">Fuchsia</Badge>
  <Badge variant="magenta">Magenta</Badge>
  <Badge variant="yellow">Yellow</Badge>
</Flex>

Packages @Adobe React Spectrum Docs Breadcrumbs Breadcrumbs (`packages/@adobe/react-spectrum/docs/breadcrumbs/Breadcrumbs.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/breadcrumbs';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/breadcrumbs/package.json';

import {Breadcrumbs, Item} from '@react-spectrum/breadcrumbs';
import {View} from '@react-spectrum/view';

category: Navigation keywords: [collections, dropdown] Copy Chapter

Breadcrumbs

{docs.exports.Breadcrumbs.description}

<HeaderInfo
packageData={packageData}
componentNames={['Breadcrumbs', 'Item']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/breadcrumbs/'}
]}
since="3.0.0" />

Example Copy Chapter

<Breadcrumbs>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

Content Copy Chapter

Breadcrumbs follow the Collection Components API, accepting only static children.
Similar to Menu, Breadcrumbs accepts <> elements as children,
each with a key prop, which is passed to the onAction handler to identify the selected item.
Basic usage of Breadcrumbs, as seen in the example above, shows a list of elements,
populated with a string. See Events for more information.

Internationalization Copy Section

In order to internationalize Breadcrumbs, the content of all child items should be localized.

Events Copy Chapter

Use the onAction prop as a callback to handle press events on items.

function Example() {
  let folders = [
    {id: 1, label: 'Home'},
    {id: 2, label: 'Trendy'},
    {id: 3, label: 'March 2020 Assets'}
  ];
  let [folderId, setFolderId] = React.useState(null);
  return (
    <div>
      <Breadcrumbs onAction={(a) => setFolderId(a)}>
        {folders.map(f => <Item key={f.id}>{f.label}</Item>)}
      </Breadcrumbs>
      <p>You pressed folder ID: {folderId}</p>
    </div>
  );
}

Links Copy Chapter

By default, interacting with an item in Breadcrumbs triggers onAction. Items may also be links to another page or website. This can be achieved by passing the href prop to the `` component.

<Breadcrumbs>
  <Item href="#">Home</Item>
  <Item href="#">React Spectrum</Item>
  <Item>Breadcrumbs</Item>
</Breadcrumbs>

Client side routing Copy Section

The `` component works with frameworks and client side routers like Next.js and React Router. As with other React Spectrum components that support links, this works via the Provider component at the root of your app. See the client side routing guide to learn how to set this up.

Props Copy Chapter

Visual options Copy Chapter

Size Copy Section

View guidelines

Small

<Breadcrumbs size="S">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

Medium

<Breadcrumbs size="M">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

Large (default)

<Breadcrumbs size="L">
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
</Breadcrumbs>

Multiline Copy Section

Use the isMultiline prop to place the last item below the other items.
This adds emphasis to the current location as a page title or heading.

<Breadcrumbs isMultiline>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

Root context Copy Section

View guidelines

Some applications find that always displaying the root item is useful to orient users.
This variation keeps the root visible when other items are truncated into the menu.

<View overflow="hidden" width="200px">
  <Breadcrumbs showRoot>
    <Item key="home">Home</Item>
    <Item key="trendy">Trendy</Item>
    <Item key="2020 assets">March 2020 Assets</Item>
    <Item key="winter">Winter</Item>
    <Item key="holiday">Holiday</Item>
  </Breadcrumbs>
</View>

Disabled Copy Section

Breadcrumbs in a disabled state shows items, but indicates that navigation is not available.
This can be used to maintain layout continuity.

<Breadcrumbs isDisabled>
  <Item key="home">Home</Item>
  <Item key="trendy">Trendy</Item>
  <Item key="march 2020 assets">March 2020 Assets</Item>
</Breadcrumbs>

Visible items (overflow behavior) Copy Section

View guidelines

Breadcrumbs collapses items into a menu when space is limited. It will only show a maximum of 4 visible items including the root and menu button, if either are visible. If the root item cannot be rendered in the available horizontal
space, it will be collapsed into the menu regardless of showRoot. Note that the last breadcrumb item will automatically
truncate with an ellipsis instead of collapsing into the menu.

Resize your browser window to see the above behavior in the examples below.

<Breadcrumbs>
  <Item key="shared">My Shared Documents</Item>
  <Item key="catalogue">North America Spring Catalogue</Item>
  <Item key="march 2020">March 2020</Item>
  <Item key="assets">Downloaded Screenshots and Assets (approval required)</Item>
  <Item key="streetwear">Streetwear</Item>
  <Item key="jackets">Jackets</Item>
</Breadcrumbs>

<Breadcrumbs showRoot>
  <Item key="shared">My Shared Documents</Item>
  <Item key="catalogue">North America Spring Catalogue</Item>
  <Item key="march 2020">March 2020</Item>
  <Item key="assets">Downloaded Screenshots and Assets (approval required)</Item>
</Breadcrumbs>

Packages @Adobe React Spectrum Docs Button ActionButton (`packages/@adobe/react-spectrum/docs/button/ActionButton.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/button';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/button/package.json';

import {ActionButton} from '@react-spectrum/button';
import {View} from '@react-spectrum/view';
import {Flex} from '@react-spectrum/layout';

category: Buttons keywords: [action button] Copy Chapter

ActionButton

{docs.exports.ActionButton.description}

<HeaderInfo
packageData={packageData}
componentNames={['ActionButton']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/action-button/'}
]}
since="3.0.0" />

Example Copy Chapter

<ActionButton>Edit</ActionButton>

Content Copy Chapter

ActionButtons can have a label, an icon, or both. An icon is provided by passing an icon component as a child to the ActionButton.
A visible label can be provided by passing a string or a Text component as a child, depending on whether the ActionButton has an accompanying icon.

import {Text} from '@react-spectrum/text';
import Edit from '@spectrum-icons/workflow/Edit';

<ActionButton>
  <Edit />
  <Text>Icon + Label</Text>
</ActionButton>

Accessibility Copy Section

If no visible label is provided (e.g. an icon only button),
an alternative text label must be provided to identify the control for accessibility. This should be added using
the aria-label prop.

<ActionButton aria-label="Icon only">
  <Edit />
</ActionButton>

Internationalization Copy Section

In order to internationalize an ActionButton, a localized string should be passed to the children or aria-label prop.

Events Copy Chapter

ActionButtons support user interactions via mouse, keyboard, and touch. You can handle all of these via the onPress
prop.

The following example uses an onPress handler to update a counter stored in React state.

function Example() {
  let [count, setCount] = React.useState(0);

  return (
   <ActionButton onPress={() => setCount(c => c + 1)}>{count} Edits</ActionButton>
  );
}

Props Copy Chapter

Visual options Copy Chapter

Quiet Copy Section

View guidelines

<ActionButton isQuiet>Action!</ActionButton>

Disabled Copy Section

View guidelines

<ActionButton isDisabled>Action!</ActionButton>

Static color Copy Section

The staticColor prop can be used when an ActionButton is displayed over a color background. You are responsible for
choosing the static color variant that ensures the text meets an
accessible contrast ratio
with the background.

<Flex wrap gap="size-250">
  <View backgroundColor="static-blue-700" padding="size-500">
    <ActionButton staticColor="white">
      <Edit />
      <Text>Edit</Text>
    </ActionButton>
  </View>
  <View backgroundColor="static-yellow-400" padding="size-500">
    <ActionButton staticColor="black" isQuiet>
      <Edit />
      <Text>Edit</Text>
    </ActionButton>
  </View>
</Flex>

Packages @Adobe React Spectrum Docs Button Button (`packages/@adobe/react-spectrum/docs/button/Button.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/button';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/button/package.json';

import {Button} from '@react-spectrum/button';
import Bell from '@spectrum-icons/workflow/Bell';
import {View} from '@react-spectrum/view';
import {Flex} from '@react-spectrum/layout';

category: Buttons Copy Chapter

Button

{docs.exports.Button.description}

<HeaderInfo
packageData={packageData}
componentNames={['Button']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/button/'}
]}
since="3.0.0" />

Example Copy Chapter

<Button variant="accent">Save</Button>

Content Copy Chapter

Buttons must have a visible label, and can optionally have an icon. Text only buttons accept a string
as children. Icons can also be added as children, with a sibling Text element for the label.

import {Text} from '@react-spectrum/text';

<Button variant="primary">
  <Bell />
  <Text>Icon + Label</Text>
</Button>

Accessibility Copy Section

If no visible label is provided (e.g. an icon only button),
an alternative text label must be provided to identify the control for accessibility. This should be added using
the aria-label prop.

Internationalization Copy Section

In order to internationalize a button, a localized string should be passed to the children or aria-label prop.

Events Copy Chapter

Buttons support user interactions via mouse, keyboard, and touch. You can handle all of these via the onPress
prop.

The following example uses an onPress handler to update a counter stored in React state.

function Example() {
  let [count, setCount] = React.useState(0);

  return (
    <Button variant="primary" onPress={() => setCount(c => c + 1)}>{count} Dogs</Button>
  );
}

Pending Copy Chapter

Buttons can indicate that a quick progress task is taking place (e.g., saving settings on a server). After a 1 second delay, an indeterminate spinner will be displayed in place of the button label and icon. You can trigger this behavior with the isPending prop. Button events are disabled while isPending is true.

function Example() {
  let [isLoading, setIsLoading] = React.useState(false);

  let handlePress = () => {
    // Trigger button pending state
    setIsLoading(true);

    setTimeout(() => {
      // Cancel button pending state
      setIsLoading(false);
    }, 3000);
  };

  return (
    <Button variant="primary" isPending={isLoading} onPress={handlePress}>Click me!</Button>
  );
}

Props Copy Chapter

Visual options Copy Chapter

Accent Copy Section

View guidelines

<Flex wrap gap="size-250">
  <Button variant="accent" style="fill">Save</Button>
  <Button variant="accent" style="outline">Save</Button>
</Flex>

Primary Copy Section

View guidelines

<Flex wrap gap="size-250">
  <Button variant="primary" style="fill">Save</Button>
  <Button variant="primary" style="outline">Save</Button>
</Flex>

Secondary Copy Section

View guidelines

<Flex wrap gap="size-250">
  <Button variant="secondary" style="fill">Save</Button>
  <Button variant="secondary" style="outline">Save</Button>
</Flex>

Negative Copy Section

View guidelines

<Flex wrap gap="size-250">
  <Button variant="negative" style="fill">Save</Button>
  <Button variant="negative" style="outline">Save</Button>
</Flex>

Static color Copy Section

View guidelines

<Flex wrap gap="size-250">
  <View backgroundColor="static-blue-700" padding="size-500">
    <Flex wrap gap="size-200">
      <Button variant="primary" staticColor="white" style="fill">Save</Button>
      <Button variant="primary" staticColor="white" style="outline">Save</Button>
    </Flex>
  </View>
  <View backgroundColor="static-yellow-400" padding="size-500">
    <Flex wrap gap="size-200">
      <Button variant="primary" staticColor="black" style="fill">Save</Button>
      <Button variant="primary" staticColor="black" style="outline">Save</Button>
    </Flex>
  </View>
</Flex>

Disabled Copy Section

View guidelines

<Button variant="accent" isDisabled>Save</Button>

Icon only Copy Section

View guidelines

<Flex direction="row" gap={8}>
  <Button variant="accent" aria-label="Ring for service"><Bell /></Button>
  <Button variant="primary" aria-label="Ring for service"><Bell /></Button>
  <Button variant="secondary" aria-label="Ring for service"><Bell /></Button>
</Flex>

Packages @Adobe React Spectrum Docs Button LogicButton (`packages/@adobe/react-spectrum/docs/button/LogicButton.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/button';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/button/package.json';

import {LogicButton} from '@react-spectrum/button';

category: Buttons keywords: [logic button] Copy Chapter

LogicButton

{docs.exports.LogicButton.description}

<HeaderInfo
packageData={packageData}
componentNames={['LogicButton']}
since="3.0.0" />

Example Copy Chapter

<LogicButton variant="and">And</LogicButton>

Content Copy Chapter

LogicButtons must have a variant and optionally can have a label.
A visible label can be provided by passing children.

<LogicButton variant="or">Or</LogicButton>

Internationalization Copy Section

In order to internationalize a LogicButton, a localized string should be passed to the children or aria-label prop.

Events Copy Chapter

LogicButton supports user interactions via mouse, keyboard, and touch. You can handle all of these via the onPress prop.

The following example uses an onPress handler to update the variant.

function Example() {
  let [variant, setVariant] = React.useState<'and' | 'or'>('or');

  return (
    <LogicButton variant={variant} onPress={() => setVariant(variant === 'or' ? 'and' : 'or')}>{variant}</LogicButton>
  );
}

Props Copy Chapter

Visual options Copy Chapter

Variant Copy Section

<LogicButton variant="or" marginEnd="20px">Or</LogicButton>
<LogicButton variant="and">And</LogicButton>

Disabled Copy Section

<LogicButton variant="or" isDisabled>Or</LogicButton>

Packages @Adobe React Spectrum Docs Button ToggleButton (`packages/@adobe/react-spectrum/docs/button/ToggleButton.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/button';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/button/package.json';

import {Flex} from '@react-spectrum/layout';
import {ToggleButton} from '@react-spectrum/button';
import {View} from '@react-spectrum/view';

category: Buttons keywords: [toggle button] Copy Chapter

ToggleButton

{docs.exports.ToggleButton.description}

<HeaderInfo
packageData={packageData}
componentNames={['ToggleButton']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/action-button/'}
]}
since="3.2.0" />

Example Copy Chapter

<ToggleButton>Pin</ToggleButton>

Content Copy Chapter

ToggleButtons can have a label, an icon, or both. An icon is provided by passing an icon component as a child to the ToggleButton.
A visible label can be provided by passing a string or a Text component as a child, depending on whether the ToggleButton has an accompanying icon.

import {Text} from '@react-spectrum/text';
import Pin from '@spectrum-icons/workflow/PinOff';

<ToggleButton>
  <Pin />
  <Text>Icon + Label</Text>
</ToggleButton>

Accessibility Copy Section

If no visible label is provided (e.g. an icon only button),
an alternative text label must be provided to identify the control for accessibility. This should be added using
the aria-label prop.

<ToggleButton aria-label="Icon only">
  <Pin />
</ToggleButton>

Note: ToggleButton should not be used when the content of the button changes between selection states, for example,
mute/unmute or play/pause. In these cases, use an ActionButton instead.

Internationalization Copy Section

In order to internationalize an ToggleButton, a localized string should be passed to the children or aria-label prop.

Value Copy Chapter

ToggleButtons are not selected by default. The defaultSelected prop can be used to set the default state (uncontrolled).
Alternatively, the isSelected prop can be used to make the selected state controlled. See React's documentation on
uncontrolled components for more info, and Events, below,
for an example of controlled behavior.

Events Copy Chapter

ToggleButtons support user interactions via mouse, keyboard, and touch. When pressing the button, the selection
state is toggled, and the onChange event is fired. The following example uses an onChange handler to update React state.

function Example() {
  let [isSelected, setSelected] = React.useState(false);

  return (
    <ToggleButton
      isEmphasized
      isSelected={isSelected}
      onChange={setSelected}
      aria-label="Pin">
      <Pin />
    </ToggleButton>
  );
}

Props Copy Chapter

Visual options Copy Chapter

Quiet Copy Section

View guidelines

<ToggleButton isQuiet>Pin</ToggleButton>

Disabled Copy Section

View guidelines

<ToggleButton isDisabled>Pin</ToggleButton>

Emphasized Copy Section

View guidelines

<ToggleButton isEmphasized defaultSelected>Pin</ToggleButton>

Static color Copy Section

The staticColor prop can be used when a ToggleButton is displayed over a color background. When selected, the icon and text
automatically take on the color of the background. You are responsible for choosing the static color variant that ensures the
text meets an accessible contrast ratio
with the background.

<Flex wrap gap="size-250">
  <View backgroundColor="static-blue-700" padding="size-500">
    <ToggleButton staticColor="white">
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
  <View backgroundColor="static-yellow-400" padding="size-500">
    <ToggleButton staticColor="black" isQuiet defaultSelected>
      <Pin />
      <Text>Pin</Text>
    </ToggleButton>
  </View>
</Flex>

Packages @Adobe React Spectrum Docs Buttongroup ButtonGroup (`packages/@adobe/react-spectrum/docs/buttongroup/ButtonGroup.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/buttongroup';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/buttongroup/package.json';

category: Buttons keywords: [button group] Copy Chapter

ButtonGroup

{docs.exports.ButtonGroup.description}

<HeaderInfo
packageData={packageData}
componentNames={['ButtonGroup']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/button-group/'}
]}
since="3.0.0" />

Example Copy Chapter

import {ButtonGroup} from '@react-spectrum/buttongroup';
import {Button} from '@react-spectrum/button';

<ButtonGroup>
  <Button variant="primary">Rate Now</Button>
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
</ButtonGroup>

Content Copy Chapter

ButtonGroup expects Buttons as children and is used to handle overflow. When horizontal space is limited, the ButtonGroup switches to a vertical layout. ButtonGroup should be used when there are two or more related Buttons in a group.
To see the orientation switch in the example above, resize the width of your window.

Props Copy Chapter

Visual options Copy Chapter

Orientation Copy Section

View guidelines

Setting this to 'vertical' will prevent any dynamic orientation changes, the ButtonGroup will remain in vertical regardless of the available width.

<ButtonGroup orientation="vertical">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

Alignment Copy Section

View guidelines

Button groups are aligned contextually. Generally, button groups should be start-aligned to follow content. However, they should be end-aligned inside container components, such as in dialogs, popovers, or cards. Center alignment should be used in the context of an empty state. In right-to-left languages, alignment is flipped automatically.

<ButtonGroup orientation="vertical" align="end">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

<ButtonGroup orientation="vertical" align="center">
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

Disabled Copy Section

View guidelines

<ButtonGroup isDisabled>
  <Button variant="secondary">No, thanks</Button>
  <Button variant="secondary">Remind me later</Button>
  <Button variant="primary">Rate Now</Button>
</ButtonGroup>

Packages @Adobe React Spectrum Docs Calendar Calendar (`packages/@adobe/react-spectrum/docs/calendar/Calendar.mdx`) Copy Section

{/* Copyright 2022 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-spectrum/calendar';
import i18nDocs from 'docs:@internationalized/date';
import {HeaderInfo, PropTable, PageDescription, TypeLink} from '@react-spectrum/docs';
import packageData from '@react-spectrum/calendar/package.json';

import {Calendar} from '@react-spectrum/calendar';
import {Flex} from '@react-spectrum/layout';
import {ActionButton} from '@adobe/react-spectrum';

category: Date and Time keywords: [date] Copy Chapter

Calendar

{docs.exports.Calendar.description}

<HeaderInfo
packageData={packageData}
componentNames={['Calendar']}
sourceData={[]}
since="3.19.0" />

Example Copy Chapter

<Calendar aria-label="Event date" />

Value Copy Chapter

A Calendar has no selection by default. An initial, uncontrolled value can be provided to the Calendar using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

Date values are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

Calendar supports values with both date and time components, but only allows users to modify the date. By default, Calendar will emit objects in the onChange event, but if a or object is passed as the value or defaultValue, values of that type will be emitted, changing only the date and preserving the time components.

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] = React.useState(parseDate('2020-02-03'));

  return (
    <Flex gap="size-300" wrap>
      <Calendar
        aria-label="Date (uncontrolled)"
        defaultValue={parseDate('2020-02-03')} />
      <Calendar
        aria-label="Date (controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}

International calendars Copy Section

Calendar supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the Provider component.

Selected dates passed to onChange always use the same calendar system as the value or defaultValue prop. If no value or defaultValue is provided, then dates passed to onChange are always in the Gregorian calendar since this is the most commonly used. This means that even though the user selects dates in their local calendar system, applications are able to deal with dates from all users consistently.

The below example displays a Calendar in the Hindi language, using the Indian calendar. Dates emitted from onChange are in the Gregorian calendar.

import {Provider} from '@adobe/react-spectrum';

function Example() {
  let [date, setDate] = React.useState(null);
  return (
    <Provider locale="hi-IN-u-ca-indian">
      <Calendar aria-label="Date" value={date} onChange={setDate} />
      <p>Selected date: {date?.toString()}</p>
    </Provider>
  );
}

Custom calendar systems Copy Section

Calendar also supports custom calendar systems that implement custom business rules. An example would be a fiscal year calendar that follows a 4-5-4 format, where month ranges don't follow the usual Gregorian calendar.

The createCalendar prop accepts a function that returns an instance of the interface. See the @internationalized/date docs for an example implementation.

import type {AnyCalendarDate} from '@internationalized/date';
import {CalendarDate, startOfWeek, toCalendar} from '@internationalized/date';

/* Detailed source-code truncated for AI context efficiency. */

Labeling Copy Chapter

An aria-label must be provided to the Calendar for accessibility. If it is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization Copy Section

In order to internationalize a Calendar, a localized string should be passed to the aria-label prop. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the Calendar is automatically flipped. Dates are automatically formatted using the current locale.

Events Copy Chapter

Calendar accepts an onChange prop which is triggered whenever a date is selected by the user. The example below uses onChange to update a separate element with a formatted version of the date in the user's locale. This is done by converting the date to a native JavaScript Date object to pass to the formatter.

import {getLocalTimeZone} from '@internationalized/date';
import {useDateFormatter} from '@adobe/react-spectrum';

function Example() {
  let [date, setDate] = React.useState(parseDate('2022-07-04'));
  let formatter = useDateFormatter({dateStyle: 'full'});

  return (
    <>
      <Calendar aria-label="Event date" value={date} onChange={setDate} />
      <p>Selected date: {formatter.format(date.toDate(getLocalTimeZone()))}</p>
    </>
  );
}

Validation Copy Chapter

By default, Calendar allows selecting any date. The minValue and maxValue props can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

import {today} from '@internationalized/date';

<Calendar aria-label="Appointment date" minValue={today(getLocalTimeZone())} />

Unavailable dates Copy Section

Calendar supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance. The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.

This example includes multiple unavailable date ranges, e.g. dates when no appointments are available. In addition, all weekends are unavailable. The minValue prop is also used to prevent selecting dates before today.

import {today, isWeekend} from '@internationalized/date';
import {useLocale} from '@adobe/react-spectrum';

function Example() {
  let now = today(getLocalTimeZone());
  let disabledRanges = [
    [now, now.add({days: 5})],
    [now.add({days: 14}), now.add({days: 16})],
    [now.add({days: 23}), now.add({days: 24})],
  ];

  let {locale} = useLocale();
  let isDateUnavailable = (date) => isWeekend(date, locale) || disabledRanges.some((interval) => date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0);

  return <Calendar aria-label="Appointment date" minValue={today(getLocalTimeZone())} isDateUnavailable={isDateUnavailable} />
}

Controlling the focused date Copy Chapter

By default, the selected date is focused when a Calendar first mounts. If no value or defaultValue prop is provided, then the current date is focused. However, Calendar supports controlling which date is focused using the focusedValue and onFocusChange props. This also determines which month is visible. The defaultFocusedValue prop allows setting the initial focused date when the Calendar first mounts, without controlling it.

This example focuses July 1, 2021 by default. The user may change the focused date, and the onFocusChange event updates the state. Clicking the button resets the focused date back to the initial value.

import {CalendarDate} from '@internationalized/date';

function Example() {
  let defaultDate = new CalendarDate(2021, 7, 1);
  let [focusedDate, setFocusedDate] = React.useState(defaultDate);

  return (
    <Flex direction="column" alignItems="start" gap="size-200">
      <ActionButton onPress={() => setFocusedDate(defaultDate)}>Reset focused date</ActionButton>
      <Calendar focusedValue={focusedDate} onFocusChange={setFocusedDate} />
    </Flex>
  );
}

Props Copy Chapter

Visual options Copy Chapter

Disabled Copy Section

<Calendar aria-label="Event date" isDisabled />

Read only Copy Section

The isReadOnly boolean prop makes the Calendar's value immutable. Unlike isDisabled, the Calendar remains focusable.

<Calendar aria-label="Event date" value={today(getLocalTimeZone())} isReadOnly />

Visible months Copy Section

By default, the Calendar displays a single month. The visibleMonths prop allows displaying up to 3 months at a time.

<div style={{maxWidth: '100%', overflow: 'auto'}}>
  <Calendar aria-label="Event date" visibleMonths={3} />
</div>

Page behavior Copy Section

By default, when pressing the next or previous buttons, pagination will advance by the visibleMonths value. This behavior can be changed to page by single months instead, by setting pageBehavior to single.

<div style={{maxWidth: '100%', overflow: 'auto'}}>
  <Calendar aria-label="Event date" visibleMonths={3} pageBehavior="single" />
</div>

Custom first day of week Copy Section

By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the firstDayOfWeek prop to 'sun', 'mon', 'tue', 'wed', 'thu', 'fri', or 'sat'.

<div style={{maxWidth: '100%', overflow: 'auto'}}>
  <Calendar aria-label="Event date" firstDayOfWeek="mon" />
</div>

Packages @Adobe React Spectrum Docs Calendar RangeCalendar (`packages/@adobe/react-spectrum/docs/calendar/RangeCalendar.mdx`) Copy Section

{/* Copyright 2022 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-spectrum/calendar';
import i18nDocs from 'docs:@internationalized/date';
import {HeaderInfo, PropTable, PageDescription, TypeLink} from '@react-spectrum/docs';
import packageData from '@react-spectrum/calendar/package.json';

import {RangeCalendar} from '@react-spectrum/calendar';
import {Flex} from '@react-spectrum/layout';
import {ActionButton} from '@adobe/react-spectrum';

category: Date and Time keywords: [date] Copy Chapter

RangeCalendar

{docs.exports.RangeCalendar.description}

<HeaderInfo
packageData={packageData}
componentNames={['RangeCalendar']}
sourceData={[]}
since="3.19.0" />

Example Copy Chapter

<RangeCalendar aria-label="Trip dates" />

Value Copy Chapter

A RangeCalendar has no selection by default. An initial, uncontrolled value can be provided to the RangeCalendar using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.

Date ranges are objects with start and end properties containing date values, which are provided using objects in the @internationalized/date package. This library handles correct international date manipulation across calendars, time zones, and other localization concerns.

RangeCalendar supports values with both date and time components, but only allows users to modify the dates. By default, RangeCalendar will emit objects in the onChange event, but if a or object is passed as the value or defaultValue, values of that type will be emitted, changing only the date and preserving the time components.

import {parseDate} from '@internationalized/date';

function Example() {
  let [value, setValue] = React.useState({
    start: parseDate('2020-02-03'),
    end: parseDate('2020-02-12')
  });

  return (
    <Flex gap="size-300" wrap>
      <RangeCalendar
        aria-label="Date range (uncontrolled)"
        defaultValue={{
          start: parseDate('2020-02-03'),
          end: parseDate('2020-02-12')
        }} />
      <RangeCalendar
        aria-label="Date range (controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}

International calendars Copy Section

RangeCalendar supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more. Dates are automatically displayed in the appropriate calendar system for the user's locale. The calendar system can be overridden using the Unicode calendar locale extension, passed to the Provider component.

Selected dates passed to onChange always use the same calendar system as the value or defaultValue prop. If no value or defaultValue is provided, then dates passed to onChange are always in the Gregorian calendar since this is the most commonly used. This means that even though the user selects dates in their local calendar system, applications are able to deal with dates from all users consistently.

The below example displays a RangeCalendar in the Hindi language, using the Indian calendar. Dates emitted from onChange are in the Gregorian calendar.

import {Provider} from '@adobe/react-spectrum';

function Example() {
  let [range, setRange] = React.useState(null);
  return (
    <Provider locale="hi-IN-u-ca-indian">
      <RangeCalendar aria-label="Date range" value={range} onChange={setRange} />
      <p>Start date: {range?.start.toString()}</p>
      <p>End date: {range?.end.toString()}</p>
    </Provider>
  );
}

Custom calendar systems Copy Section

RangeCalendar also supports custom calendar systems that implement custom business rules. An example would be a fiscal year calendar that follows a 4-5-4 format, where month ranges don't follow the usual Gregorian calendar.

The createCalendar prop accepts a function that returns an instance of the interface. See the @internationalized/date docs for an example implementation.

import type {AnyCalendarDate} from '@internationalized/date';
import {CalendarDate, startOfWeek, toCalendar} from '@internationalized/date';

/* Detailed source-code truncated for AI context efficiency. */

Labeling Copy Chapter

An aria-label must be provided to the RangeCalendar for accessibility. If it is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization Copy Section

In order to internationalize a RangeCalendar, a localized string should be passed to the aria-label prop. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the RangeCalendar is automatically flipped. Dates are automatically formatted using the current locale.

Events Copy Chapter

RangeCalendar accepts an onChange prop which is triggered whenever a date is selected by the user. The example below uses onChange to update a separate element with a formatted version of the date in the user's locale. This is done by converting the date to a native JavaScript Date object to pass to the formatter.

import {getLocalTimeZone} from '@internationalized/date';
import {useDateFormatter} from '@adobe/react-spectrum';

function Example() {
  let [range, setRange] = React.useState({
    start: parseDate('2020-07-03'),
    end: parseDate('2020-07-10')
  });
  let formatter = useDateFormatter({dateStyle: 'long'});

  return (
    <>
      <RangeCalendar aria-label="Date range" value={range} onChange={setRange} />
      <p>
        Selected date:{' '}
        {formatter.formatRange(
          range.start.toDate(getLocalTimeZone()),
          range.end.toDate(getLocalTimeZone())
        )}
      </p>
    </>
  );
}

Validation Copy Chapter

By default, RangeCalendar allows selecting any date range. The minValue and maxValue props can also be used to prevent the user from selecting dates outside a certain range.

This example only accepts dates after today.

import {today} from '@internationalized/date';

<RangeCalendar aria-label="Trip dates" minValue={today(getLocalTimeZone())} />

Unavailable dates Copy Section

RangeCalendar supports marking certain dates as unavailable. These dates cannot be selected by the user and are displayed with a crossed out appearance. The isDateUnavailable prop accepts a callback that is called to evaluate whether each visible date is unavailable.

Note that by default, users may not select non-contiguous ranges, i.e. ranges that contain unavailable dates within them. Once a start date is selected, enabled dates will be restricted to subsequent dates until an unavailable date is hit. See below for an example of how to allow non-contiguous ranges.

This example includes multiple unavailable date ranges, e.g. dates when a rental house is not available. The minValue prop is also used to prevent selecting dates before today.

import {today} from '@internationalized/date';

function Example() {
  let now = today(getLocalTimeZone());
  let disabledRanges = [
    [now, now.add({days: 5})],
    [now.add({days: 14}), now.add({days: 16})],
    [now.add({days: 23}), now.add({days: 24})],
  ];

  let isDateUnavailable = (date) => disabledRanges.some((interval) => date.compare(interval[0]) >= 0 && date.compare(interval[1]) <= 0);

  return <RangeCalendar aria-label="Trip dates" minValue={today(getLocalTimeZone())} isDateUnavailable={isDateUnavailable} />
}

Non-contiguous ranges Copy Section

The allowsNonContiguousRanges prop enables a range to be selected even if there are unavailable dates in the middle. The value emitted in the onChange event will still be a single range with a start and end property, but unavailable dates will not be displayed as selected. It is up to applications to split the full selected range into multiple as needed for business logic.

This example prevents selecting weekends, but allows selecting ranges that span multiple weeks.

import {isWeekend} from '@internationalized/date';
import {useLocale} from '@adobe/react-spectrum';

function Example() {
  let {locale} = useLocale();

  return <RangeCalendar aria-label="Time off request" isDateUnavailable={date => isWeekend(date, locale)} allowsNonContiguousRanges />
}

Controlling the focused date Copy Chapter

By default, the first selected date is focused when a RangeCalendar first mounts. If no value or defaultValue prop is provided, then the current date is focused. However, RangeCalendar supports controlling which date is focused using the focusedValue and onFocusChange props. This also determines which month is visible. The defaultFocusedValue prop allows setting the initial focused date when the RangeCalendar first mounts, without controlling it.

This example focuses July 1, 2021 by default. The user may change the focused date, and the onFocusChange event updates the state. Clicking the button resets the focused date back to the initial value.

import {CalendarDate} from '@internationalized/date';

function Example() {
  let defaultDate = new CalendarDate(2021, 7, 1);
  let [focusedDate, setFocusedDate] = React.useState(defaultDate);

  return (
    <Flex direction="column" alignItems="start" gap="size-200">
      <ActionButton onPress={() => setFocusedDate(defaultDate)}>Reset focused date</ActionButton>
      <RangeCalendar focusedValue={focusedDate} onFocusChange={setFocusedDate} />
    </Flex>
  );
}

Props Copy Chapter

Visual options Copy Chapter

Disabled Copy Section

<RangeCalendar aria-label="Trip dates" isDisabled />

Read only Copy Section

The isReadOnly boolean prop makes the RangeCalendar's value immutable. Unlike isDisabled, the RangeCalendar remains focusable.

<RangeCalendar aria-label="Trip dates" value={{start: today(getLocalTimeZone()), end: today(getLocalTimeZone()).add({ weeks: 1 })}} isReadOnly />

Visible months Copy Section

By default, a RangeCalendar displays a single month. The visibleMonths prop allows displaying up to 3 months at a time.

<div style={{maxWidth: '100%', overflow: 'auto'}}>
  <RangeCalendar aria-label="Trip dates" visibleMonths={3} />
</div>

Page behavior Copy Section

By default, when pressing the next or previous buttons, pagination will advance by the visibleMonths value. This behavior can be changed to page by single months instead, by setting pageBehavior to single.

<div style={{maxWidth: '100%', overflow: 'auto'}}>
  <RangeCalendar aria-label="Trip dates" visibleMonths={3} pageBehavior="single" />
</div>

Custom first day of week Copy Section

By default, the first day of the week is automatically set based on the current locale. This can be changed by setting the firstDayOfWeek prop to 'sun', 'mon', 'tue', 'wed', 'thu', 'fri', or 'sat'.

<div style={{maxWidth: '100%', overflow: 'auto'}}>
  <RangeCalendar aria-label="Trip dates" firstDayOfWeek="mon" />
</div>

Packages @Adobe React Spectrum Docs Checkbox Checkbox (`packages/@adobe/react-spectrum/docs/checkbox/Checkbox.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/checkbox';
import packageData from '@react-spectrum/checkbox/package.json';
import {HeaderInfo, PropTable, PageDescription} from '@react-spectrum/docs';

import {Checkbox} from '@react-spectrum/checkbox';
 import {View} from '@react-spectrum/view';
 import {Flex} from '@react-spectrum/layout';

category: Forms keywords: [input] Copy Chapter

Checkbox

{docs.exports.Checkbox.description}

<HeaderInfo
packageData={packageData}
componentNames={['Checkbox']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/checkbox/'}
]}
since="3.0.0" />

Example Copy Chapter

<Checkbox>Unsubscribe</Checkbox>

Content Copy Chapter

Checkboxes accept children, which are rendered as the label.

Accessibility Copy Section

In certain cases a visible label isn't needed. For example, a checkbox used to select a table row.
If a visible label isn't specified, an aria-label must be provided to the Checkbox for accessibility.
If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization Copy Section

To internationalize a Checkbox, a localized label should be passed to the children or aria-label prop.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the checkbox is automatically flipped.

Value Copy Chapter

Checkboxes are not selected by default. The defaultSelected prop can be used to set the default state (uncontrolled).
Alternatively, the isSelected prop can be used to make the selected state controlled. See React's documentation on uncontrolled components for more info.

function Example() {
  let [selected, setSelected] = React.useState(true);

  return (
    <Flex direction="row">
      <Checkbox defaultSelected>Subscribe (uncontrolled)</Checkbox>
      <Checkbox isSelected={selected} onChange={setSelected}>Subscribe (controlled)</Checkbox>
    </Flex>
  );
}

Indeterminate Copy Section

View guidelines

A Checkbox can be in an indeterminate state, controlled using the isIndeterminate prop.
This overrides the appearance of the Checkbox, whether selection is controlled or uncontrolled.
The Checkbox will visually remain indeterminate until the isIndeterminate prop is set to false, regardless of user interaction.

<Checkbox isIndeterminate>Subscribe</Checkbox>

HTML forms Copy Section

Checkbox supports the name and value props for integration with HTML forms.

<Checkbox name="newsletter" value="subscribe">Subscribe</Checkbox>

Events Copy Chapter

Checkboxes accept a user defined onChange prop, triggered whenever the Checkbox is clicked.
The example below uses onChange to alert the user to changes in the checkbox's state.

function Example() {
  let [selected, setSelection] = React.useState(false);

  return (
    <Flex direction="column">
      <Checkbox isSelected={selected} onChange={setSelection}>
        Subscribe
      </Checkbox>
      <View>{`You are ${selected ? 'subscribed' : 'unsubscribed'}`}</View>
    </Flex>
  );
 }

Validation Copy Chapter

Checkboxes can display a validation state to communicate to the user if the current value is invalid.
Implement your own validation logic in your app and set the isInvalid prop accordingly.
The invalid state is only communicated via a color change so in order to be accessible the validation error must also be communicated in another way.

<Checkbox isInvalid>I accept the terms and conditions</Checkbox>

Props Copy Chapter

Visual options Copy Chapter

Disabled Copy Section

View guidelines

<Checkbox isDisabled>Subscribe</Checkbox>

Emphasized Copy Section

View guidelines

<Checkbox isEmphasized defaultSelected>Subscribe</Checkbox>

Packages @Adobe React Spectrum Docs Checkbox CheckboxGroup (`packages/@adobe/react-spectrum/docs/checkbox/CheckboxGroup.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/checkbox';
import packageData from '@react-spectrum/checkbox/package.json';
import {HeaderInfo, PropTable, PageDescription, VersionBadge, ClassAPI} from '@react-spectrum/docs';

import {Checkbox, CheckboxGroup} from '@react-spectrum/checkbox';
 import {Flex} from '@react-spectrum/layout';

category: Forms keywords: [input, checkbox group, accessibility] after_version: 3.1.0 Copy Chapter

CheckboxGroup

{docs.exports.CheckboxGroup.description}

<HeaderInfo
packageData={packageData}
componentNames={['CheckboxGroup', 'Checkbox']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/checkbox/'}
]}
since="3.0.0" />

Example Copy Chapter

<CheckboxGroup label="Favorite sports">
  <Checkbox value="soccer">Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

Content Copy Chapter

CheckboxGroup accepts multiple Checkbox elements as children.
Each Checkbox represents an option that can be selected, labeled by its children.

Value Copy Chapter

CheckboxGroup supports selecting zero or more items. An initial, uncontrolled value can be provided to the CheckboxGroup using the defaultValue prop.
Alternatively, a controlled value can be provided using the value prop. Both of these props accept an array of selected items, which map to the
value prop on each item.

function Example() {
  let [selected, setSelected] = React.useState(['soccer', 'baseball']);

  return (
    <Flex gap="size-300">
      <CheckboxGroup label="Favorite sports (uncontrolled)" defaultValue={['soccer', 'baseball']}>
        <Checkbox value="soccer">Soccer</Checkbox>
        <Checkbox value="baseball">Baseball</Checkbox>
        <Checkbox value="basketball">Basketball</Checkbox>
      </CheckboxGroup>

      <CheckboxGroup label="Favorite sports (controlled)" value={selected} onChange={setSelected}>
        <Checkbox value="soccer">Soccer</Checkbox>
        <Checkbox value="baseball">Baseball</Checkbox>
        <Checkbox value="basketball">Basketball</Checkbox>
      </CheckboxGroup>
    </Flex>
  );
}

HTML forms Copy Section

CheckboxGroup supports the name prop, paired with the Checkbox value prop, for integration with HTML forms.

<CheckboxGroup label="Condiments" name="condiments">
  <Checkbox value="mayo">Mayo</Checkbox>
  <Checkbox value="mustart">Mustard</Checkbox>
  <Checkbox value="ketchup">Ketchup</Checkbox>
</CheckboxGroup>

Labeling Copy Chapter

A visual label should be provided for the CheckboxGroup using the label prop. If the CheckboxGroup requires an option to be selected by the user,
the isRequired and necessityIndicator props can be used to show a required state.

<Flex gap="size-300" wrap>
  <CheckboxGroup label="Favorite sports">
    <Checkbox value="soccer">Soccer</Checkbox>
    <Checkbox value="baseball">Baseball</Checkbox>
    <Checkbox value="basketball">Basketball</Checkbox>
  </CheckboxGroup>
  <CheckboxGroup label="Favorite sports" isRequired necessityIndicator="icon">
    <Checkbox value="soccer">Soccer</Checkbox>
    <Checkbox value="baseball">Baseball</Checkbox>
    <Checkbox value="basketball">Basketball</Checkbox>
  </CheckboxGroup>
  <CheckboxGroup label="Favorite sports" isRequired necessityIndicator="label">
    <Checkbox value="soccer">Soccer</Checkbox>
    <Checkbox value="baseball">Baseball</Checkbox>
    <Checkbox value="basketball">Basketball</Checkbox>
  </CheckboxGroup>
  <CheckboxGroup label="Favorite sports" necessityIndicator="label">
    <Checkbox value="soccer">Soccer</Checkbox>
    <Checkbox value="baseball">Baseball</Checkbox>
    <Checkbox value="basketball">Basketball</Checkbox>
  </CheckboxGroup>
</Flex>

Accessibility Copy Section

If a visible label isn't specified for a CheckboxGroup, an aria-label must be provided for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Checkbox elements within a group should always have a visible label.

Internationalization Copy Section

To internationalize a CheckboxGroup, a localized string should be passed to the label prop and as the child content of the Checkbox elements.
For languages that are read right-to-left (e.g. Hebrew and Arabic), the Checkbox is automatically placed on the right side of the text. When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Events Copy Chapter

CheckboxGroup accepts an onChange prop, which is triggered when a user adds or removes an item from the selection.
The example below uses onChange to log how the user is interacting with the component.

function Example() {
  let [selected, setSelected] = React.useState([]);

  return (
    <>
      <CheckboxGroup label="Favorite sports" value={selected} onChange={setSelected}>
        <Checkbox value="soccer">Soccer</Checkbox>
        <Checkbox value="baseball">Baseball</Checkbox>
        <Checkbox value="basketball">Basketball</Checkbox>
      </CheckboxGroup>
      <div>You have selected: {selected.join(', ')}</div>
    </>
  );
}

Validation Copy Chapter

CheckboxGroup supports the isRequired prop to ensure the user selects at least one item, as well as custom client and server-side validation. Individual checkboxes also support validation, and errors from all checkboxes are aggregated at the group level. CheckboxGroup can also be integrated with other form libraries. See the Forms guide to learn more.

Group validation Copy Section

The isRequired prop at the CheckboxGroup level requires that at least one item is selected. When the Form component has the validationBehavior="native" prop, validation errors block form submission and are displayed as help text automatically.

import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';

<Form validationBehavior="native">
  {/*- begin highlight -*/}
  <CheckboxGroup label="Sandwich condiments" name="condiments" isRequired>
  {/*- end highlight -*/}
    <Checkbox value="lettuce">Lettuce</Checkbox>
    <Checkbox value="tomato">Tomato</Checkbox>
    <Checkbox value="onion">Onion</Checkbox>
    <Checkbox value="sprouts">Sprouts</Checkbox>
  </CheckboxGroup>
  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>

By default, CheckboxGroup displays default validation messages provided by the browser. See Customizing error messages in the Forms guide to learn how to provide your own custom errors.

Individual Checkbox validation Copy Section

To require that specific checkboxes are checked, set the isRequired prop at the Checkbox level instead of the CheckboxGroup. The following example shows how to require that all items are selected.

<Form validationBehavior="native">
  <CheckboxGroup label="Agree to the following" isRequired>
    {/*- begin highlight -*/}
    <Checkbox value="terms" isRequired>Terms and conditions</Checkbox>
    <Checkbox value="privacy" isRequired>Privacy policy</Checkbox>
    <Checkbox value="cookies" isRequired>Cookie policy</Checkbox>
    {/*- end highlight -*/}
  </CheckboxGroup>
  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>

Props Copy Chapter

Visual options Copy Chapter

Orientation Copy Section

CheckboxGroups are vertically oriented by default.
The orientation prop can be used to change the orientation to horizontal.

<CheckboxGroup label="Favorite sports" orientation="horizontal">
  <Checkbox value="soccer">Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

Label position and alignment Copy Section

By default, the label is positioned above the CheckboxGroup.
The labelPosition prop can be used to position the label to the side. The labelAlign prop can
be used to align the label as "start" or "end".
For left-to-right (LTR) languages, "start" refers to the left most edge of the CheckboxGroup
and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

<CheckboxGroup label="Favorite sports" labelPosition="side" labelAlign="end">
  <Checkbox value="soccer">Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

Help text Copy Section

View guidelines

Both a description and an error message can be supplied to a CheckboxGroup. The description is always visible unless the isInvalid is true and an error message is provided. The error message can be used to help the user fix their input quickly and should be specific to the detected error. All strings should be localized.

function Example() {
  let [checked, setChecked] = React.useState(['dogs', 'dragons']);
  let isValid = checked.length === 2 && checked.includes('dogs') && checked.includes('dragons');

  return (
    <CheckboxGroup
      label="Pets"
      onChange={setChecked}
      value={checked}
      isInvalid={!isValid}
      description="Select your pets."
      errorMessage={
        checked.includes('cats')
          ? 'No cats allowed.'
          : 'Select only dogs and dragons.'
      }>
      <Checkbox value="dogs">Dogs</Checkbox>
      <Checkbox value="cats">Cats</Checkbox>
      <Checkbox value="dragons">Dragons</Checkbox>
    </CheckboxGroup>
  );
}

Contextual help Copy Section

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

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

<CheckboxGroup
  label="Favorite genres"
  contextualHelp={
    <ContextualHelp>
      <Heading>What does this do?</Heading>
      <Content>Your musical taste is used to train our machine learning recommendation algorithm.</Content>
    </ContextualHelp>
  }>
  <Checkbox value="rock">Rock</Checkbox>
  <Checkbox value="pop">Pop</Checkbox>
  <Checkbox value="classical">Classical</Checkbox>
</CheckboxGroup>

Disabled Copy Section

View guidelines

<CheckboxGroup label="Favorite sports" isDisabled>
  <Checkbox value="soccer">Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

<CheckboxGroup label="Favorite sports">
  <Checkbox value="soccer">Soccer</Checkbox>
  <Checkbox value="baseball" isDisabled>Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

Read only Copy Section

View guidelines

The isReadOnly prop makes the selection immutable. Unlike isDisabled, the CheckboxGroup remains focusable.
See the MDN docs for more information.

<CheckboxGroup label="Favorite sports" defaultValue={['baseball']} isReadOnly>
  <Checkbox value="soccer">Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

Emphasized Copy Section

View guidelines

<CheckboxGroup label="Favorite sports" defaultValue={['soccer', 'baseball']} isEmphasized>
  <Checkbox value="soccer">Soccer</Checkbox>
  <Checkbox value="baseball">Baseball</Checkbox>
  <Checkbox value="basketball">Basketball</Checkbox>
</CheckboxGroup>

Packages @Adobe React Spectrum Docs Color ColorArea (`packages/@adobe/react-spectrum/docs/color/ColorArea.mdx`) Copy Section

{/* Copyright 2020 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 colorTypes from 'docs:@react-stately/color';
import docs from 'docs:@react-spectrum/color';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import {Layout} from '@react-spectrum/docs';
import packageData from '@react-spectrum/color/package.json';
import statelyDocs from 'docs:@react-stately/color';

export default Layout;

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

category: Color keywords: [color area] Copy Chapter

ColorArea

{docs.exports.ColorArea.description}

<HeaderInfo
packageData={packageData}
componentNames={['ColorArea']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/color-area/'}
]}
since="3.35.0" />

Example Copy Chapter

<ColorArea defaultValue="#7f0000" />

Value Copy Chapter

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

HTML forms Copy Section

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" />

Labeling Copy Chapter

By default, ColorArea uses an aria-label for the localized string "Color Picker",
which labels the visually hidden `` 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>

Accessibility Copy Section

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 `` elements.

Value formatting

The aria-valuetext of each 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 element controls coming before the channel name and value for the adjacent
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 representing the
blue channel will have aria-valuetext to announce as "Blue: 0, Green: 255", and the ``
representing the green channel will have aria-valuetext to announce as "Green: 255, Blue: 0".

Internationalization Copy Section

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 `` element with the channel name and current value.

Events Copy Chapter

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

Creating a color picker Copy Chapter

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 Copy Section

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

HSLA Copy Section

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

HSBA Copy Section

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

Props Copy Chapter

Visual options Copy Chapter

Disabled Copy Section

View guidelines

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

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

Custom Size Copy Section

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>

Testing Copy Chapter

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.

Packages @Adobe React Spectrum Docs Color ColorField (`packages/@adobe/react-spectrum/docs/color/ColorField.mdx`) Copy Section

{/* Copyright 2020 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-spectrum/color';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import packageData from '@react-spectrum/color/package.json';
import statelyDocs from 'docs:@react-stately/color';

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

category: Color keywords: [color field, input] Copy Chapter

ColorField

{docs.exports.ColorField.description}

<HeaderInfo
packageData={packageData}
componentNames={['ColorField']}
sourceData={[]}
since="3.35.0" />

Example Copy Chapter

<ColorField label="Primary Color" />

Value Copy Chapter

A ColorField's value is empty by default, but an initial, uncontrolled, value can be provided using the defaultValue prop.
Alternatively, a controlled value can be provided using the value prop. The value provided to either of these props should be a color string or object.

In the example below, the function is used to parse the initial color
from a hex value, stored in state.

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

function Example() {
  let [value, setValue] = React.useState(parseColor('#e73623'));

  return (
    <Flex gap="size-150" wrap>
      <ColorField
        label="Primary Color (Uncontrolled)"
        defaultValue="#e21" />

      <ColorField
        label="Primary Color (Controlled)"
        value={value}
        onChange={setValue} />
    </Flex>
  );
}

HTML forms Copy Section

ColorField supports the name prop for integration with HTML forms. The value will be submitted to the server as a hex color string. When a channel prop is provided, the value will be submitted as a number instead.

<ColorField label="Color" name="color" />

Color channel Copy Chapter

By default, ColorField allows the user to edit the color as a hex value. When the colorSpace and channel props are provided, ColorField displays the value for that channel formatted as a number instead. Rendering multiple ColorFields together can allow a user to edit a color.

function Example() {
  let [color, setColor] = React.useState(parseColor('#7f007f'));
  return (
    <>
      <div style={{display: 'flex', gap: 8}}>
        <ColorField label="Hue" value={color} onChange={setColor} colorSpace="hsl" channel="hue" />
        <ColorField label="Saturation" value={color} onChange={setColor} colorSpace="hsl" channel="saturation" />
        <ColorField label="Lightness" value={color} onChange={setColor} colorSpace="hsl" channel="lightness" />
      </div>
      <p>Current color value: {color?.toString('hex')}</p>
    </>
  );
}

Labeling Copy Chapter

A visual label should be provided for the ColorField using the label prop. If the ColorField is required, the isRequired and
necessityIndicator props can be used to show a required state.

<Flex gap="size-150" wrap>
  <ColorField label="Primary Color" />
  <ColorField label="Primary Color" isRequired />
  <ColorField label="Primary Color" isRequired necessityIndicator="label" />
  <ColorField label="Primary Color" necessityIndicator="label" />
</Flex>

Accessibility Copy Section

If a visible label isn't specified, an aria-label must be provided to the ColorField for
accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using
the id of the labeling element instead.

Internationalization Copy Section

In order to internationalize a ColorField, a localized string should be passed to the label or aria-label prop.
When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Validation Copy Chapter

ColorField supports the isRequired prop to ensure the user enters a value, as well as custom validation functions, realtime validation, and server-side validation. It can also be integrated with other form libraries. See the Forms guide to learn more.

When the Form component has the validationBehavior="native" prop, validation errors block form submission and are displayed as help text automatically. Errors are displayed when the user blurs the color field or submits the form.

import {Form, ButtonGroup, Button} from '@adobe/react-spectrum';

<Form validationBehavior="native" maxWidth="size-3000">
  {/*- begin highlight -*/}
  <ColorField label="Color" name="color" isRequired />
  {/*- end highlight -*/}
  <ButtonGroup>
    <Button type="submit" variant="primary">Submit</Button>
    <Button type="reset" variant="secondary">Reset</Button>
  </ButtonGroup>
</Form>

By default, ColorField displays default validation messages provided by the browser. See Customizing error messages in the Forms guide to learn how to provide your own custom errors.

Props Copy Chapter

Visual options Copy Chapter

Quiet Copy Section

<ColorField label="Primary Color" isQuiet />

Disabled Copy Section

<ColorField label="Primary Color" isDisabled defaultValue="#e73623" />

Read only Copy Section

The isReadOnly boolean prop makes the ColorField's text content immutable. Unlike isDisabled, the ColorField remains focusable
and the contents can still be copied. See the MDN docs for more information.

<ColorField label="Primary Color" isReadOnly defaultValue="#e73623" />

Label alignment and position Copy Section

View guidelines

By default, the label is positioned above the ColorField. The labelPosition prop can be used to position the label to the side.
The labelAlign prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the
left most edge of the ColorField and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

<ColorField label="Primary Color" labelPosition="side" labelAlign="end" />

Help text Copy Section

View guidelines

Both a description and an error message can be supplied to a ColorField. The description is always visible unless the validationState is “invalid” and an error message is provided. The error message can be used to help the user fix their input quickly and should be specific to the detected error. All strings should be localized.

<Flex gap="size-100" wrap>
  <ColorField label="Color" defaultValue="#abc" validationState="valid" description="Enter your favorite color." />
  <ColorField label="Color" validationState="invalid" errorMessage="Empty input is not allowed." />
</Flex>

Contextual help Copy Section

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

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

<ColorField
  label="Accent Color"
  defaultValue="#e73623"
  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>
  } />

Custom width Copy Section

View guidelines

<ColorField label="Primary Color" width="size-3600" maxWidth="100%" />

Packages @Adobe React Spectrum Docs Color ColorPicker (`packages/@adobe/react-spectrum/docs/color/ColorPicker.mdx`) Copy Section

{/* Copyright 2020 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 colorTypes from 'docs:@react-stately/color';
import docs from 'docs:@react-spectrum/color';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import {Layout} from '@react-spectrum/docs';
import packageData from '@react-spectrum/color/package.json';
import statelyDocs from 'docs:@react-stately/color';

export default Layout;

import {ColorPicker, ColorEditor} from '@react-spectrum/color';
import {Flex} from '@react-spectrum/layout';

category: Color keywords: [color picker] Copy Chapter

ColorPicker

{docs.exports.ColorPicker.description}

<HeaderInfo
packageData={packageData}
componentNames={['ColorPicker', 'ColorEditor']}
since="3.35.0" />

Example Copy Chapter

<ColorPicker label="Fill" defaultValue="#5100FF">
  <ColorEditor />
</ColorPicker>

Value Copy Chapter

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

In the example below, the function is used to parse the initial color from a HSL string so that value's type remains consistent.

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

function Example() {
  let [value, setValue] = React.useState(parseColor('hsl(25, 100%, 50%)'));
  return (
    <Flex gap="size-300" wrap>
      <ColorPicker
        label="Color Picker (uncontrolled)"
        /*- begin highlight -*/
        defaultValue="hsl(25, 100%, 50%)">
        {/*- end highlight -*/}
        <ColorEditor />
      </ColorPicker>
      <ColorPicker
        label="Color Picker (controlled)"
        /*- begin highlight -*/
        value={value}
        onChange={setValue}>
        {/*- end highlight -*/}
        <ColorEditor />
      </ColorPicker>
    </Flex>
  );
}

Labeling Copy Chapter

A visual label should be provided for the ColorPicker using the label prop.

<ColorPicker label="Stroke color" defaultValue="#345">
  <ColorEditor />
</ColorPicker>

Accessibility Copy Section

If a visible label isn't specified, an aria-label should be provided to the ColorPicker for
accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using
the id of the labeling element instead.

<ColorPicker aria-label="Fill color" defaultValue="#184">
  <ColorEditor />
</ColorPicker>

In addition to the visible or accessibility label, a ColorPicker also announces a description of the current color value (e.g. "dark vibrant blue") as a part of the label.

Internationalization Copy Section

For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the ColorPicker is automatically flipped.

Events Copy Chapter

ColorPicker accepts an onChange prop which is triggered whenever the value is edited by the user. It receives a object as a parameter.

The example below uses onChange to update a separate element with the color value as a string.

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

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

  return (
    <div>
      <ColorPicker
        label="Color"
        value={value}
        onChange={setValue}>
        <ColorEditor />
      </ColorPicker>
      <p>Selected color: {value.toString('hsl')}</p>
    </div>
  );
}

Custom color editor Copy Chapter

ColorEditor provides a default color picker layout including a color area for saturation and brightness, and color sliders for hue and alpha. It also includes ColorFields to view and enter an exact color value by number.

ColorPicker can be customized by providing any combination of color components as children, including ColorArea, ColorField, ColorSlider, ColorSwatchPicker, and ColorWheel.

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

<ColorPicker label="Fill" defaultValue="#08f">
  <ColorWheel />
  <ColorArea
    colorSpace="hsb"
    xChannel="saturation"
    yChannel="brightness"
    size="size-400"
    position="absolute"
    top="calc(50% - size-400)"
    left="calc(50% - size-400)" />
</ColorPicker>

Props Copy Chapter

ColorPicker Copy Section

ColorEditor Copy Section

Visual options Copy Chapter

Hide alpha channel Copy Section

By default, ColorEditor includes a ColorSlider and ColorField for editing the alpha channel. This can be hidden with the hideAlphaChannel prop.

<ColorPicker label="Color" defaultValue="#f80">
  <ColorEditor hideAlphaChannel />
</ColorPicker>

Swatches Copy Section

A ColorEditor can be combined with additional color components such as a ColorSwatchPicker to choose from a list of pre-defined colors.

import {ColorSwatchPicker, ColorSwatch} from '@react-spectrum/color';

<ColorPicker label="Color" defaultValue="#A00">
  <Flex direction="column" gap="size-300">
    <ColorEditor />
    <ColorSwatchPicker>
      <ColorSwatch color="#A00" />
      <ColorSwatch color="#f80" />
      <ColorSwatch color="#080" />
      <ColorSwatch color="#08f" />
      <ColorSwatch color="#088" />
      <ColorSwatch color="#008" />
    </ColorSwatchPicker>
  </Flex>
</ColorPicker>

Channel sliders Copy Section

This example uses ColorSlider to allow a user to adjust each channel of a color value, with a Picker to switch between color spaces.

import type {ColorSpace} from '@react-spectrum/color';
import {ColorSlider, getColorChannels} from '@react-spectrum/color';
import {Picker, Item} from '@react-spectrum/picker';

function Example() {
  let [space, setSpace] = React.useState<ColorSpace>('rgb');

  return (
    <ColorPicker label="Color" defaultValue="#184">
      <Flex direction="column" gap="size-100">
        <Picker aria-label="Color space" isQuiet selectedKey={space} onSelectionChange={s => setSpace(s as ColorSpace)}>
          <Item key="rgb">RGB</Item>
          <Item key="hsl">HSL</Item>
          <Item key="hsb">HSB</Item>
        </Picker>
        {getColorChannels(space).map(channel => (
          <ColorSlider key={channel} colorSpace={space} channel={channel} />
        ))}
        <ColorSlider channel="alpha" />
      </Flex>
    </ColorPicker>
  );
}

Rounding Copy Section

The rounding of the color swatch can be controlled with the rounding prop.

<Flex direction="column" gap="size-100">
  <ColorPicker label="None" rounding="none" defaultValue="#A00">
    <ColorEditor />
  </ColorPicker>
  <ColorPicker label="Default" rounding="default" defaultValue="#080">
    <ColorEditor />
  </ColorPicker>
  <ColorPicker label="Full" rounding="full" defaultValue="#00F">
    <ColorEditor />
  </ColorPicker>
</Flex>

Size Copy Section

The size of the color swatch can be controlled with the size prop. The default size is "S".

<Flex direction="column" gap="size-100">
  <ColorPicker label="Extra small" size="XS" defaultValue="#A00">
    <ColorEditor />
  </ColorPicker>
  <ColorPicker label="Small" size="S" defaultValue="#080">
    <ColorEditor />
  </ColorPicker>
  <ColorPicker label="Medium" size="M" defaultValue="#FB0">
    <ColorEditor />
  </ColorPicker>
  <ColorPicker label="Large" size="L" defaultValue="#00F">
    <ColorEditor />
  </ColorPicker>
</Flex>

Packages @Adobe React Spectrum Docs Color ColorSlider (`packages/@adobe/react-spectrum/docs/color/ColorSlider.mdx`) Copy Section

{/* Copyright 2020 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 colorTypes from 'docs:@react-stately/color';
import docs from 'docs:@react-spectrum/color';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import {Layout} from '@react-spectrum/docs';
import packageData from '@react-spectrum/color/package.json';
import statelyDocs from 'docs:@react-stately/color';

export default Layout;

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

category: Color keywords: [color slider] Copy Chapter

ColorSlider

{docs.exports.ColorSlider.description}

<HeaderInfo
packageData={packageData}
componentNames={['ColorSlider']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/color-slider/'}
]}
since="3.35.0" />

Example Copy Chapter

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

Value Copy Chapter

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

HTML forms Copy Section

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" />

Labeling Copy Chapter

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>

Accessibility Copy Section

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 Copy Section

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 Copy Chapter

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

Creating a color picker Copy Chapter

RGBA Copy Section

This example shows how you could build an RGBA color picker using four color sliders bound to the same
color value in state. The
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>
  );
}

HSLA Copy Section

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

HSBA Copy Section

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

Props Copy Chapter

Visual options Copy Chapter

Disabled Copy Section

View guidelines

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

Vertical Copy Section

View guidelines

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

Custom Size Copy Section

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>

Contextual help Copy Section

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>
  } />

Testing Copy Chapter

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.

Packages @Adobe React Spectrum Docs Color ColorSwatch (`packages/@adobe/react-spectrum/docs/color/ColorSwatch.mdx`) Copy Section

{/* 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 colorTypes from 'docs:@react-stately/color';
import docs from 'docs:@react-spectrum/color';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import {Layout} from '@react-spectrum/docs';
import packageData from '@react-spectrum/color/package.json';
import statelyDocs from 'docs:@react-stately/color';

export default Layout;

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

category: Color keywords: [color swatch] Copy Chapter

ColorSwatch

{docs.exports.ColorSwatch.description}

<HeaderInfo
packageData={packageData}
componentNames={['ColorSwatch']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/swatch/'}
]}
since="3.35.0" />

Example Copy Chapter

<ColorSwatch color="#f00" />

Value Copy Chapter

ColorSwatch accepts a value via the color prop. The value should be a color string or object.

In the example below, the function is used to parse the initial color from an HSL string. This is passed to the value prop of a ColorSlider, and the color prop of a ColorSwatch to show a preview of the selected color.

import {parseColor, ColorSlider} from '@react-spectrum/color';

function Example() {
  let [color, setColor] = React.useState(parseColor('hsl(0, 100%, 50%)'));
  return (
    <Flex direction="column" gap="size-100">
      <ColorSlider value={color} onChange={setColor} channel="hue" />
      <ColorSwatch color={color} />
    </Flex>
  );
}

Fully transparent colors are displayed with a red slash through the swatch, while partially transparent colors are shown with a checkerboard background.

import {parseColor, ColorSlider} from '@react-spectrum/color';

function Example() {
  let [color, setColor] = React.useState(parseColor('hsla(0, 100%, 50%, 0)'));
  return (
    <Flex direction="column" gap="size-100">
      <ColorSlider value={color} onChange={setColor} channel="alpha" />
      <ColorSwatch color={color} />
    </Flex>
  );
}

Labeling Copy Chapter

By default, ColorSwatch includes a localized color description for screen reader users (e.g. "dark vibrant blue") as an aria-label. If you have a more specific color name (e.g. Pantone colors), the automatically generated color description can be overridden via the colorName prop. An additional label describing the context of the color swatch (e.g. "Background color") can also be provided via the aria-label or aria-labelledby props.

In the example below, the full accessible name of the color swatch will be "Fire truck red, Background color".

<ColorSwatch color="#f00" aria-label="Background color" colorName="Fire truck red" />

Props Copy Chapter

Visual options Copy Chapter

Size Copy Section

View guidelines

<Flex gap="size-100">
  <ColorSwatch color="#ff0" size="XS" />
  <ColorSwatch color="#ff0" size="S" />
  <ColorSwatch color="#ff0" size="M" />
  <ColorSwatch color="#ff0" size="L" />
</Flex>

Rounding Copy Section

View guidelines

<Flex gap="size-100">
  <ColorSwatch color="#0ff" rounding="none" />
  <ColorSwatch color="#0ff" rounding="default" />
  <ColorSwatch color="#0ff" rounding="full" />
</Flex>

Custom width Copy Section

View guidelines

<ColorSwatch color="#00f" width="size-1000" />

Packages @Adobe React Spectrum Docs Color ColorSwatchPicker (`packages/@adobe/react-spectrum/docs/color/ColorSwatchPicker.mdx`) Copy Section

{/* 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 colorTypes from 'docs:@react-stately/color';
import docs from 'docs:@react-spectrum/color';
import {HeaderInfo, PropTable, TypeLink, PageDescription} from '@react-spectrum/docs';
import {Layout} from '@react-spectrum/docs';
import packageData from '@react-spectrum/color/package.json';
import statelyDocs from 'docs:@react-stately/color';

export default Layout;

import {ColorSwatchPicker, ColorSwatch} from '@react-spectrum/color';

category: Color keywords: [color swatch] Copy Chapter

ColorSwatchPicker

{docs.exports.ColorSwatchPicker.description}

<HeaderInfo
packageData={packageData}
componentNames={['ColorSwatchPicker']}
sourceData={[
{type: 'Spectrum', url: 'https://spectrum.adobe.com/page/swatch-group/'}
]}
since="3.35.0" />

Example Copy Chapter

<ColorSwatchPicker>
  <ColorSwatch color="#A00" />
  <ColorSwatch color="#f80" />
  <ColorSwatch color="#080" />
  <ColorSwatch color="#08f" />
  <ColorSwatch color="#088" />
  <ColorSwatch color="#008" />
</ColorSwatchPicker>

Value Copy Chapter

ColorSwatchPicker accepts 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 object. The value is matched against the color of each ColorSwatch, including equivalent colors in different color spaces.

In the example below, the function is used to parse the initial color from a HSL string so that value's type remains consistent.

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

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

  return (
    <ColorSwatchPicker value={color} onChange={setColor}>
      <ColorSwatch color="#A00" />
      <ColorSwatch color="#f80" />
      <ColorSwatch color="#080" />
    </ColorSwatchPicker>
  );
}

Note: ColorSwatches rendered inside a ColorSwatchPicker must have unique colors, even between different color spaces. For example, the values #f00, hsl(0, 100%, 50%), and hsb(0, 100%, 100%) are all equivalent and considered duplicates. This is required so that selection behavior works properly.

Labeling Copy Chapter

By default, ColorSwatchPicker has an aria-label with the localized string "Color swatches". This can be overridden with a more specific accessibility label using the aria-label or aria-labelledby props. All labels should be localized.

<ColorSwatchPicker aria-label="Fill color">
  <ColorSwatch color="#A00" />
  <ColorSwatch color="#f80" />
  <ColorSwatch color="#080" />
</ColorSwatchPicker>

Events Copy Chapter

ColorSwatchPicker accepts an onChange prop which is triggered whenever the value is edited by the user. It receives a object as a parameter.

The example below uses onChange to update a separate element with the color value as a string.

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

function Example() {
  let [value, setValue] = React.useState(parseColor('#A00'));

  return (
    <div>
      <ColorSwatchPicker value={value} onChange={setValue}>
        <ColorSwatch color="#A00" />
        <ColorSwatch color="#f80" />
        <ColorSwatch color="#080" />
        <ColorSwatch color="#08f" />
        <ColorSwatch color="#088" />
        <ColorSwatch color="#008" />
      </ColorSwatchPicker>
      <p>Selected color: {value.toString('rgb')}</p>
    </div>
  );
}

Props Copy Chapter

Visual options Copy Chapter