List
Structured list container with optional selection, keyboard navigation, and multiple visual variants. Pairs with arc-list-item for rich content rows.
<arc-list>Overview
List provides a semantic container for ordered collections of items. It handles keyboard navigation (arrow keys, Home, End), optional single or multi-select behavior, and visual variants that control border and separator styles.
When selectable is set, the list renders with role="listbox" and manages aria-selected states across its child arc-list-item elements. Selection state is tracked via a comma-separated value string, making it easy to bind in any framework. The arc-change event fires on each selection change with the current value in event.detail.
Three visual variants cover the common list presentations: default (plain), bordered (outlined container), and separated (bottom borders between items). A size prop controls the base font size for the entire list, cascading down to child items.
Guidelines
When to use
- Use arc-list-item as direct children for consistent styling and keyboard navigation
- Put per-row buttons (rename, delete) in the `actions` slot of a plain list, and give each one a label naming its row: "Rename Weekly review", not "Rename"
- Mark the current row of an actionable list with `href` and `selected`, which sets aria-current; a selectable list is a listbox and cannot hold row actions
- Set `selectable` when items represent choices the user needs to pick from
- Use the bordered variant inside cards or panels that need visual containment
- Use the separated variant for long lists where row boundaries improve scannability
When not to use
- Do not use List for navigation menus. Use `arc-navigation-menu` or `arc-dropdown-menu` instead
- Do not mix arc-list-item with raw HTML elements inside a selectable list
- Do not nest lists more than one level deep. Consider a tree view for hierarchical data
Features
- Full keyboard navigation with Arrow Up/Down, Home, End, Enter, and Space
- Single and multi-select modes with `value` binding and `arc-change` events
- Three visual variants: default, bordered, separated
- Three size presets (sm, md, lg) that cascade to child items
- Semantic `role="listbox"` when selectable, `role="list"` otherwise
- Automatic `aria-multiselectable` when `multiple` is set
- Row actions: an `actions` slot on arc-list-item, revealed on hover or focus and always shown without hover, that never selects the row
- Exposed CSS part: list
Preview
Usage
This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.
<arc-list variant="bordered" selectable>
<arc-list-item value="inbox">
<arc-icon slot="prefix" name="inbox"></arc-icon>
Inbox
<arc-badge slot="suffix" variant="primary">12</arc-badge>
</arc-list-item>
<arc-list-item value="drafts">
<arc-icon slot="prefix" name="file-text"></arc-icon>
Drafts
</arc-list-item>
<arc-list-item value="sent">
<arc-icon slot="prefix" name="send"></arc-icon>
Sent
</arc-list-item>
</arc-list>import { List, ListItem, Icon, Badge } from '@arclux/arc-ui-react';
export default function Example() {
return (
<List variant="bordered" selectable>
<ListItem value="inbox">
<Icon slot="prefix" name="inbox" />
Inbox
<Badge slot="suffix" variant="primary">12</Badge>
</ListItem>
<ListItem value="drafts">
<Icon slot="prefix" name="file-text" />
Drafts
</ListItem>
<ListItem value="sent">
<Icon slot="prefix" name="send" />
Sent
</ListItem>
</List>
);
}<script setup>
import { List, ListItem, Icon, Badge } from '@arclux/arc-ui-vue';
</script>
<template>
<List variant="bordered" selectable>
<ListItem value="inbox">
<Icon slot="prefix" name="inbox" />
Inbox
<Badge slot="suffix" variant="primary">12</Badge>
</ListItem>
<ListItem value="drafts">
<Icon slot="prefix" name="file-text" />
Drafts
</ListItem>
</List>
</template><script>
import { List, ListItem, Icon, Badge } from '@arclux/arc-ui-svelte';
</script>
<List variant="bordered" selectable>
<ListItem value="inbox">
<Icon slot="prefix" name="inbox" />
Inbox
<Badge slot="suffix" variant="primary">12</Badge>
</ListItem>
<ListItem value="drafts">
<Icon slot="prefix" name="file-text" />
Drafts
</ListItem>
</List>import { Component } from '@angular/core';
import { List, ListItem, Icon, Badge } from '@arclux/arc-ui-angular';
@Component({
imports: [List, ListItem, Icon, Badge],
template: `
<arc-list variant="bordered" selectable>
<arc-list-item value="inbox">
<arc-icon slot="prefix" name="inbox" />
Inbox
<arc-badge slot="suffix" variant="primary">12</arc-badge>
</arc-list-item>
<arc-list-item value="drafts">
<arc-icon slot="prefix" name="file-text" />
Drafts
</arc-list-item>
</arc-list>
`,
})
export class MailboxComponent {}import { List, ListItem, Icon, Badge } from '@arclux/arc-ui-solid';
export default function Example() {
return (
<List variant="bordered" selectable>
<ListItem value="inbox">
<Icon slot="prefix" name="inbox" />
Inbox
<Badge slot="suffix" variant="primary">12</Badge>
</ListItem>
<ListItem value="drafts">
<Icon slot="prefix" name="file-text" />
Drafts
</ListItem>
</List>
);
}import { List, ListItem, Icon, Badge } from '@arclux/arc-ui-preact';
export default function Example() {
return (
<List variant="bordered" selectable>
<ListItem value="inbox">
<Icon slot="prefix" name="inbox" />
Inbox
<Badge slot="suffix" variant="primary">12</Badge>
</ListItem>
<ListItem value="drafts">
<Icon slot="prefix" name="file-text" />
Drafts
</ListItem>
</List>
);
}API
valuestring''- The currently selected value(s). Comma-separated when
multipleis true. The selection itself is held as a list of values, so a value containing a comma is selected and rendered correctly; only the *serialised* multi-select string cannot represent one, since the comma is its separator. Single-select is exact for any value. labelstring''- Accessible name for the list, applied as
aria-label. Required whenselectableis set so the listbox has an accessible name. variant'default' | 'bordered' | 'separated''default'- Visual style. Bordered wraps the list in an outlined container. Separated adds bottom borders between items.
size'sm' | 'md' | 'lg''md'- Scale of the list's rows: their text, padding and height.
smis a dense list such as a sidebar; its rows keep the touch-target minimum (larger on touch screens). selectablebooleanfalse- Enables selection mode. Sets
role="listbox"and managesaria-selectedon child items. multiplebooleanfalse- Allows multiple items to be selected simultaneously. Only applies when
selectableis true.
Events
arc-selectdetail:{ value: string }- Fired from the activated arc-list-item when a selectable list is driven by Enter or Space.
arc-changedetail:{ value: string }- Fired when the selection changes.
event.detail.valuecontains the new value string.
List Item
<arc-list-item>Individual row within an arc-list. Supports prefix/suffix slots, a description slot for secondary text, an actions slot for per-row buttons, links, and selection state.
valuestring''- Unique identifier used for selection tracking.
hrefstring''- When set, renders the item as an anchor tag for navigation.
selectedbooleanfalse- Whether this item is currently selected. Managed automatically by a selectable parent list. On an
hrefitem in a plain list it marks the current page instead (aria-current="page"), which is the accessible way to show the current row in a list whose rows carry actions. disabledbooleanfalse- Prevents interaction and dims the item.
Events
arc-selectdetail:{ value: string }- Fired when the item is activated: by click, or by Enter or Space on a focused row (in a selectable list the parent dispatches it from this element). Cancelable: on an
hrefrow, cancelling it stops the link navigating, which is how a single-page app routes the click itself. A modified click (Ctrl, Cmd, Shift, a middle click) is left to the browser and does not fire it.
See Also
- Data GridA spreadsheet-grade grid for working with tabular data: inline cell editing, multi-column sorting, pinned columns, row selection, and virtualized rendering. Columns are defined as a JavaScript array, and the grid implements the full WAI-ARIA grid keyboard pattern with a single tab stop.
- Navigation MenuHorizontal navigation bar with hover-triggered dropdown sub-menus and full keyboard accessibility. Designed for marketing sites, documentation hubs, and product landing pages where top-level sections expand into categorised link lists.
- Virtual ListWindowed list that renders only visible items for efficient scrolling through thousands of rows. Fixed item height with configurable overscan.