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

Changelog#

Version 0.18.0#

Breaking Changes

ListRow Breaking Updated BUI links to use the hosting application's client-side router, including relative destinations and the application's configured router base path, while preserving native browser navigation where required.

Anchor-based components no longer accept the React Aria render prop. BUI now owns the underlying anchor so routing behavior remains consistent across application and plugin package versions.

ListRow, Tag, and table Row now retain client-side navigation when application and plugin packages load separate React Aria copies. Their existing modifier-key, target, download, and link-metadata behavior is unchanged. #35299

Migration Guide:

Remove render props from ButtonLink, ComboboxItem, Link, MenuItem, MenuListBoxItem, SearchAutocompleteItem, SelectItem, and Tab. BUI now selects and renders the appropriate anchor or router link automatically.

Version 0.14.0#

Changes

ListRow Fixed relative href resolution for BUI link components. Relative paths like ../other are now correctly turned into absolute paths before reaching the React Aria layer, ensuring client-side navigation goes to the right place. #33597

Version 0.13.0#

Changes

List ListRow Added List and ListRow components. These provide a standalone, accessible list of interactive rows built on top of React Aria's GridList and GridListItem primitives. Rows support icons, descriptions, actions, menus, and single or multiple selection modes. #33358
List Fixed focus ring styles to use React Aria's [data-focus-visible] data attribute instead of the native CSS :focus-visible pseudo-class. This ensures keyboard focus rings render reliably when focus is managed programmatically by React Aria (e.g. inside a GridList, Menu, or Select). #33358