ActionGroup

An ActionGroup is a grouping of ActionButtons that are related to one another.

Example#

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

Content#

ActionGroups accepts a list of children, each with a key prop. It is required that the children are Item components from the @react-stately/collections library.

However, a function that returns Item components is also accepted.

const items = [
  {children: 'React', name: 'React'},
  {children: 'Add', name: 'Add'},
  {children: 'Delete', name: 'Delete'}
];
<ActionGroup items={items}>
  {item => <Item key={item.name}>{item.children}</Item>}
</ActionGroup>

Each item needs to have a key prop so it can be identified when actioned upon by a user.

See Events for more information.

Value#

ActionGroups are uncontrolled by default.

Use defaultSelectedKeys to provide a default set of selected items. The value of the selected keys must match the key prop of the items.

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

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

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

Accessibility#

If no visible label is provided (e.g. an icon only) to each item, 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#

In order to internationalize an ActionGroup, the strings of all child items should be localized.

Events#

Use the onSelectionChange prop as a callback to handle press events on items. The key prop from the selected item will be passed into the callback.

The following example uses the onSelectionChange prop to update a string stored in React state.

function Example() {
  let [lastKey, setLastKey] = React.useState(new Set());
  return (
    <div>
      <ActionGroup onSelectionChange={setLastKey}>
        <Item key="add">Add</Item>
        <Item key="delete">Delete</Item>
        <Item key="edit">Edit</Item>
      </ActionGroup>
      <p>Current selection: {lastKey}</p>
    </div>
  );
}

For multiple selections, use the selectionMode prop with the multiple value.

function Example() {
  let [selectedKeys, setSelectedKeys] = React.useState(new Set());
  return (
    <div>
      <ActionGroup selectionMode="multiple" onSelectionChange={setSelectedKeys}>
        <Item key="add">Add</Item>
        <Item key="delete">Delete</Item>
        <Item key="edit">Edit</Item>
      </ActionGroup>
      <p>Selected: {[...selectedKeys].toString()}</p>
    </div>
  );
}

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

function Example() {
  let [actedKey, setActedKey] = React.useState('');
  return (
    <div>
      <ActionGroup selectionMode="none" onAction={setActedKey}>
        <Item key="add">Add</Item>
        <Item key="delete">Delete</Item>
        <Item key="edit">Edit</Item>
      </ActionGroup>
      <p>Last action: {actedKey}</p>
    </div>
  );
}

Props#

Visual Options#

Quiet#

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

Emphasis#

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

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

Disabled#

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#

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

<ActionGroup orientation="vertical" maxWidth="32px">
  <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>