List

A list of interactive rows with support for keyboard navigation, single or multiple selection, and row actions.

React

TypeScript

JavaScript

Rust

Usage#

import { List, ListRow } from '@backstage/ui';

<List aria-label="Programming languages" items={items}>
  {item => <ListRow id={item.id}>{item.label}</ListRow>}
</List>

API reference#

List#

Container for a list of interactive rows.

Prop	Type	Default	Description
items	Iterable<T>	-	Item objects in the collection.
renderEmptyState	(props: GridListRenderProps) => ReactNode	-	Content to display when the collection is empty.
selectionMode	nonesinglemultiple	-	The type of selection allowed.
selectedKeys	allIterable<Key>	-	The currently selected keys (controlled).
defaultSelectedKeys	allIterable<Key>	-	The initial selected keys (uncontrolled).
disabledKeys	Iterable<Key>	-	Keys of items that should be disabled.
onSelectionChange	(keys: Selection) => void	-	Handler called when the selection changes.
children	ReactNode	-
className	string	-	Additional CSS class name for custom styling.

Inherits all React Aria GridList props.

ListRow#

Individual row within a List.

Prop	Type	Default	Description
id	string	-	Unique identifier for the row.
textValue	string	-	Text value for accessibility. Derived from children if string.
icon	ReactNode	-	Icon displayed before the row label.
description	string	-	Secondary description text displayed below the label.
isDisabled	boolean	-	Whether the row is disabled.
menuItems	ReactNode	-	Menu items rendered inside an automatically managed dropdown. Pass MenuItem nodes.
customActions	ReactNode	-	Custom action elements displayed on the right side of the row, e.g. tags.
children	ReactNode	-
className	string	-	Additional CSS class name for custom styling.

Inherits all React Aria GridListItem props.

Examples#

With icons#

React

TypeScript

JavaScript

Rust

<List aria-label="Programming languages" items={items}>
  {item => (
    <ListRow id={item.id} icon={item.icon}>
      {item.label}
    </ListRow>
  )}
</List>

With description#

ReactA JavaScript library for building user interfaces

TypeScriptTyped superset of JavaScript

JavaScriptThe language of the web

RustSystems programming with memory safety

GoSimple, fast, and reliable

<List aria-label="Programming languages" items={items}>
  {item => (
    <ListRow id={item.id} icon={item.icon} description={item.description}>
      {item.label}
    </ListRow>
  )}
</List>

Single selection#

React

TypeScript

JavaScript

Rust

const [selected, setSelected] = useState(new Set(['react']));

<List
  aria-label="Programming languages"
  items={items}
  selectionMode="single"
  selectedKeys={selected}
  onSelectionChange={setSelected}
>
  {item => <ListRow id={item.id}>{item.label}</ListRow>}
</List>

Multiple selection#

React

TypeScript

JavaScript

Rust

const [selected, setSelected] = useState(new Set(['react', 'typescript']));

<List
  aria-label="Programming languages"
  items={items}
  selectionMode="multiple"
  selectedKeys={selected}
  onSelectionChange={setSelected}
>
  {item => <ListRow id={item.id}>{item.label}</ListRow>}
</List>

Disabled items#

React

TypeScript

JavaScript

Rust

<List
  aria-label="Programming languages"
  items={items}
  disabledKeys={['typescript', 'rust']}
>
  {item => <ListRow id={item.id}>{item.label}</ListRow>}
</List>

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-List