Selection

Many collection components support selecting items by clicking or tapping them, or by using the keyboard. This page discusses how to handle selection events, how to control selection programmatically, and the data structures used to represent a selection.

Multiple selection#

Selection is handled by the onSelectionChange event, which is supported on most collection components. Controlled behavior is supported by the selectedKeys prop, and uncontrolled behavior is supported by the defaultSelectedKeys prop. These props are passed to the top-level collection component, and accept a set of unique item keys that are selected. This allows marking items as selected by their key even before they are loaded, which can be useful when you know what items should be selected on initial render, before data loading has completed.

Selection is represented by a Set object. You can also pass any iterable collection (e.g. an array) to the selectedKeys and defaultSelectedKeys props, but the onSelectionChange event will always pass back a Set.

Selection is supported on both static and dynamic collections. The following example shows how to implement controlled selection behavior on a static collection, but could be applied to a dynamic collection the same way.

let [selectedKeys, setSelectedKeys] = useState(new Set());

<ListBox selectedKeys={selectedKeys} onSelectionChange={setSelectedKeys}>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</ListBox>

let [selectedKeys, setSelectedKeys] = useState(new Set());

<ListBox
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}
>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</ListBox>

let [
  selectedKeys,
  setSelectedKeys
] = useState(new Set());

<ListBox
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}
>
  <Item key="one">
    One
  </Item>
  <Item key="two">
    Two
  </Item>
  <Item key="three">
    Three
  </Item>
</ListBox>

Single selection#

So far, we've discussed multiple selection. However, you may wish to limit selection to a single item instead. In some components, like a select or combo box, only single selection is supported. In this case, the singular selectedKey and defaultSelectedKey props are available instead of their plural variants. These accept a single key instead of a Set as their value, and onSelectionChange is also called with a single key.

let [selectedKey, setSelectedKey] = useState(null);

<ComboBox selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</ComboBox>

let [selectedKey, setSelectedKey] = useState(null);

<ComboBox
  selectedKey={selectedKey}
  onSelectionChange={setSelectedKey}
>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</ComboBox>

let [
  selectedKey,
  setSelectedKey
] = useState(null);

<ComboBox
  selectedKey={selectedKey}
  onSelectionChange={setSelectedKey}
>
  <Item key="one">
    One
  </Item>
  <Item key="two">
    Two
  </Item>
  <Item key="three">
    Three
  </Item>
</ComboBox>

In components which support multiple selection, you can limit the selection to a single item using the selectionMode prop. This continues to accept selectedKeys and defaultSelectedKeys as a Set, but it will only contain a single key at a time.

let [selectedKeys, setSelectedKeys] = useState(new Set());

<ListBox
  selectionMode="single"
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</ListBox>

let [selectedKeys, setSelectedKeys] = useState(new Set());

<ListBox
  selectionMode="single"
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}>
  <Item key="one">One</Item>
  <Item key="two">Two</Item>
  <Item key="three">Three</Item>
</ListBox>

let [
  selectedKeys,
  setSelectedKeys
] = useState(new Set());

<ListBox
  selectionMode="single"
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}
>
  <Item key="one">
    One
  </Item>
  <Item key="two">
    Two
  </Item>
  <Item key="three">
    Three
  </Item>
</ListBox>

Selected key data type#

As mentioned in the collection docs, there are two ways that keys can be defined for your collection items. The method you use will affect the data type you provide to your defaultSelectedKey(s) and selectedKey(s) props and what onSelectionChange returns.

If you directly specify the key on each Item using the key prop, defaultSelectedKey(s)/selectedKey(s) will expect a string/list of strings regardless of the original data type provided to the Item's key prop. As seen in the example below, the selectedKey is initialized to "2" rather than 2 despite the fact that the dataIds provided to each Item key are numbers.

let items = [
  { name: 'Aardvark', dataId: 1 },
  { name: 'Kangaroo', dataId: 2 },
  { name: 'Snake', dataId: 3 }
];

let [selectedKey, setSelectedKey] = useState('2');
<ComboBox selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
  {(item) => <Item key={item.dataId}>{item.name}</Item>}
</ComboBox>

let items = [
  { name: 'Aardvark', dataId: 1 },
  { name: 'Kangaroo', dataId: 2 },
  { name: 'Snake', dataId: 3 }
];

let [selectedKey, setSelectedKey] = useState('2');
<ComboBox
  selectedKey={selectedKey}
  onSelectionChange={setSelectedKey}
>
  {(item) => <Item key={item.dataId}>{item.name}</Item>}
</ComboBox>

let items = [
  {
    name: 'Aardvark',
    dataId: 1
  },
  {
    name: 'Kangaroo',
    dataId: 2
  },
  {
    name: 'Snake',
    dataId: 3
  }
];

let [
  selectedKey,
  setSelectedKey
] = useState('2');
<ComboBox
  selectedKey={selectedKey}
  onSelectionChange={setSelectedKey}
>
  {(item) => (
    <Item
      key={item.dataId}
    >
      {item.name}
    </Item>
  )}
</ComboBox>

If you specify a key or id within your items array and forgo specifying a key on the Item instead, defaultSelectedKey(s)/selectedKey(s) should match the data type of the key or id. As seen in the example below, the selectedKey is initialized as a number, matching the key type of the items array.

let items = [
  { name: 'Aardvark', key: 1 },
  { name: 'Kangaroo', key: 2 },
  { name: 'Snake', key: 3 }
];

let [selectedKey, setSelectedKey] = useState(2);
<ComboBox selectedKey={selectedKey} onSelectionChange={setSelectedKey}>
  {(item) => <Item>{item.name}</Item>}
</ComboBox>

let items = [
  { name: 'Aardvark', key: 1 },
  { name: 'Kangaroo', key: 2 },
  { name: 'Snake', key: 3 }
];

let [selectedKey, setSelectedKey] = useState(2);
<ComboBox
  selectedKey={selectedKey}
  onSelectionChange={setSelectedKey}
>
  {(item) => <Item>{item.name}</Item>}
</ComboBox>

let items = [
  {
    name: 'Aardvark',
    key: 1
  },
  {
    name: 'Kangaroo',
    key: 2
  },
  {
    name: 'Snake',
    key: 3
  }
];

let [
  selectedKey,
  setSelectedKey
] = useState(2);
<ComboBox
  selectedKey={selectedKey}
  onSelectionChange={setSelectedKey}
>
  {(item) => (
    <Item>
      {item.name}
    </Item>
  )}
</ComboBox>

Dynamic data#

When data in a collection changes, the selection state may need to be updated accordingly. For example, if a selected item is deleted, it should be removed from the set of selected keys. You can do this yourself, but the useListData and useTreeData hooks can handle this automatically.

let list = useListData({
  initialItems: [
    {name: 'Aardvark'},
    {name: 'Kangaroo'},
    {name: 'Snake'}
  ],
  initialSelectedKeys: ['Kangaroo'],
  getKey: item => item.name
});

function removeItem() {
  // Removing the list item will also remove it from the selection state.
  list.remove('Kangaroo');
}

<ListBox
  items={list.items}
  selectedKeys={list.selectedKeys}
  onSelectionChange={list.setSelectedKeys}>
  {item => <Item key={item.name}>{item.name}</Item>}
</ListBox>

let list = useListData({
  initialItems: [
    { name: 'Aardvark' },
    { name: 'Kangaroo' },
    { name: 'Snake' }
  ],
  initialSelectedKeys: ['Kangaroo'],
  getKey: (item) => item.name
});

function removeItem() {
  // Removing the list item will also remove it from the selection state.
  list.remove('Kangaroo');
}

<ListBox
  items={list.items}
  selectedKeys={list.selectedKeys}
  onSelectionChange={list.setSelectedKeys}
>
  {(item) => <Item key={item.name}>{item.name}</Item>}
</ListBox>

let list = useListData({
  initialItems: [
    { name: 'Aardvark' },
    { name: 'Kangaroo' },
    { name: 'Snake' }
  ],
  initialSelectedKeys: [
    'Kangaroo'
  ],
  getKey: (item) =>
    item.name
});

function removeItem() {
  // Removing the list item will also remove it from the selection state.
  list.remove(
    'Kangaroo'
  );
}

<ListBox
  items={list.items}
  selectedKeys={list
    .selectedKeys}
  onSelectionChange={list
    .setSelectedKeys}
>
  {(item) => (
    <Item
      key={item.name}
    >
      {item.name}
    </Item>
  )}
</ListBox>

For more information, see useListData and useTreeData.

Select All#

Some components support a checkbox to select all items in the collection, or a keyboard shortcut like ⌘ Cmd + A. This represents a selection of all items in the collection, regardless of whether or not all items have been loaded from the network. For example, when using a component with infinite scrolling support, the user will be unaware that all items are not yet loaded because it loads more transparently to them as they scroll down. For this reason, it makes sense for select all to represent all items, not just the loaded ones.

When a select all event occurs, onSelectionChange is called with the string "all" rather than a set of selected keys. selectedKeys and defaultSelectedKeys can also be set to "all" to programmatically select all items. This represents all items in the collection, whether currently loaded or not. The application must adjust its handling of bulk actions in this case to apply to the entire collection rather than only the keys available to it locally.

let [selectedKeys, setSelectedKeys] = useState(new Set());

function performBulkAction() {
  if (selectedKeys === 'all') {
    // perform action on all items
  } else {
    // perform action on selected items in selectedKeys
  }
}

<ListBox
  items={items}
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}>
  {item => <Item>{item.name}</Item>}
</ListBox>

let [selectedKeys, setSelectedKeys] = useState(new Set());

function performBulkAction() {
  if (selectedKeys === 'all') {
    // perform action on all items
  } else {
    // perform action on selected items in selectedKeys
  }
}

<ListBox
  items={items}
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}>
  {item => <Item>{item.name}</Item>}
</ListBox>

let [
  selectedKeys,
  setSelectedKeys
] = useState(new Set());

function performBulkAction() {
  if (
    selectedKeys ===
      'all'
  ) {
    // perform action on all items
  } else {
    // perform action on selected items in selectedKeys
  }
}

<ListBox
  items={items}
  selectedKeys={selectedKeys}
  onSelectionChange={setSelectedKeys}
>
  {(item) => (
    <Item>
      {item.name}
    </Item>
  )}
</ListBox>

Manages state for an immutable list data structure, and provides convenience methods to update the data over time.

useListData<T>(
  (options: ListOptions<T>
)): ListData<T>

Name	Type	Description
`initialItems`	`T[]`	Initial items in the list.
`initialSelectedKeys`	`'all' \| Iterable<Key>`	The keys for the initially selected items.
`initialFilterText`	`string`	The initial text to filter the list by.
`getKey`	`( (item: T )) => Key`	A function that returns a unique key for an item object.
`filter`	`( (item: T, , filterText: string )) => boolean`	A function that returns whether a item matches the current filter text.

string | number

Properties

Name	Type	Description
`items`	`T[]`	The items in the list.
`selectedKeys`	`Selection`	The keys of the currently selected items in the list.
`filterText`	`string`	The current filter text.

Methods

Method	Description
`setSelectedKeys( (keys: Selection )): void`	Sets the selected keys.
`setFilterText( (filterText: string )): void`	Sets the filter text.
`getItem( (key: Key )): T \| undefined`	Gets an item from the list by key.
`insert( (index: number, , ...values: T[] )): void`	Inserts items into the list at the given index.
`insertBefore( (key: Key, , ...values: T[] )): void`	Inserts items into the list before the item at the given key.
`insertAfter( (key: Key, , ...values: T[] )): void`	Inserts items into the list after the item at the given key.
`append( (...values: T[] )): void`	Appends items to the list.
`prepend( (...values: T[] )): void`	Prepends items to the list.
`remove( (...keys: Key[] )): void`	Removes items from the list by their keys.
`removeSelectedItems(): void`	Removes all items from the list that are currently in the set of selected items.
`move( (key: Key, , toIndex: number )): void`	Moves an item within the list.
`moveBefore( (key: Key, , keys: Iterable<Key> )): void`	Moves one or more items before a given key.
`moveAfter( (key: Key, , keys: Iterable<Key> )): void`	Moves one or more items after a given key.
`update( (key: Key, , newValue: T )): void`	Updates an item in the list.

'all' | Set<Key>

Manages state for an immutable tree data structure, and provides convenience methods to update the data over time.

useTreeData<T extends object>(
  (options: TreeOptions<T>
)): TreeData<T>

Name	Type	Description
`initialItems`	`object[]`	Initial root items in the tree.
`initialSelectedKeys`	`Iterable<Key>`	The keys for the initially selected items.
`getKey`	`( (item: object )) => Key`	A function that returns a unique key for an item object.
`getChildren`	`( (item: object )) => object[]`	A function that returns the children for an item object.

Properties

Name	Type	Description
`items`	`TreeNode<object>[]`	The root nodes in the tree.
`selectedKeys`	`Set<Key>`	The keys of the currently selected items in the tree.

Methods

Method	Description
`setSelectedKeys( (keys: Set<Key> )): void`	Sets the selected keys.
`getItem( (key: Key )): TreeNode<object> \| undefined`	Gets a node from the tree by key.
`insert( parentKey: Key \| \| null, index: number, ...values: object[] ): void`	Inserts an item into a parent node as a child.
`insertBefore( (key: Key, , ...values: object[] )): void`	Inserts items into the list before the item at the given key.
`insertAfter( (key: Key, , ...values: object[] )): void`	Inserts items into the list after the item at the given key.
`append( (parentKey: Key \| \| null, , ...values: object[] )): void`	Appends an item into a parent node as a child.
`prepend( (parentKey: Key \| \| null, , ...value: object[] )): void`	Prepends an item into a parent node as a child.
`remove( (...keys: Key[] )): void`	Removes an item from the tree by its key.
`removeSelectedItems(): void`	Removes all items from the tree that are currently in the set of selected items.
`move( key: Key, toParentKey: Key \| \| null, index: number ): void`	Moves an item within the tree.
`update( (key: Key, , newValue: object )): void`	Updates an item in the tree.

Name	Type	Description
`key`	`Key`	A unique key for the tree node.
`value`	`object`	The value object for the tree node.
`children`	`TreeNode<object>[] \| null`	Children of the tree node.
`parentKey`	`Key \| null`	The key of the parent node.