ActionGroup

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

Example#

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

Content#

ActionGroups accepts a list of children, each with a uniqueKey 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} itemKey="name">
  {item => <Item>{item.children}</Item>}
</ActionGroup>

Each child needs to have a uniqueKey prop so it can be identified when actioned upon by a user. If using a function, an itemKey prop is required on the ActionGroup.

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 uniqueKey prop of the items.

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

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

<ActionGroup selectedKeys={['delete']}>
  <Item uniqueKey="add">Add</Item>
  <Item uniqueKey="delete">Delete</Item>
  <Item uniqueKey="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 uniqueKey="brush" aria-label="Brush"><Brush /></Item>
  <Item uniqueKey="select" aria-label="Select"><Select /></Item>
  <Item uniqueKey="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 uniqueKey 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 uniqueKey="add">Add</Item>
        <Item uniqueKey="delete">Delete</Item>
        <Item uniqueKey="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 uniqueKey="add">Add</Item>
        <Item uniqueKey="delete">Delete</Item>
        <Item uniqueKey="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 uniqueKey="add">Add</Item>
        <Item uniqueKey="delete">Delete</Item>
        <Item uniqueKey="edit">Edit</Item>
      </ActionGroup>
      <p>Last action: {actedKey}</p>
    </div>
  );
}

Props#

Visual Options#

Quiet#

<ActionGroup isQuiet>
  <Item uniqueKey="add">Add</Item>
  <Item uniqueKey="delete">Delete</Item>
  <Item uniqueKey="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 uniqueKey="add">Add</Item>
  <Item uniqueKey="delete">Delete</Item>
  <Item uniqueKey="edit">Edit</Item>
</ActionGroup>

Disabled#

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

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

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

<ActionGroup disabledKeys={['add', 'delete']}>
  <Item uniqueKey="add">Add</Item>
  <Item uniqueKey="delete">Delete</Item>
  <Item uniqueKey="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 uniqueKey="brush" aria-label="Brush"><Brush /></Item>
  <Item uniqueKey="select" aria-label="Select"><Select /></Item>
  <Item uniqueKey="regionSelect" aria-label="Select Region"><RegionSelect /></Item>
</ActionGroup>