List

Structured list container with optional selection, keyboard navigation, and multiple visual variants. Pairs with arc-list-item for rich content rows.

Components

List

data

interactive

<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 — default (plain), bordered (outlined container), and separated (bottom borders between items) — cover the most common list presentation patterns. 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
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 — cascades to child items
Semantic `role="listbox"` when selectable, `role="list"` otherwise
Automatic `aria-multiselectable` when `multiple` is set
Exposed CSS part: list

Preview

Inbox

Drafts

Sent

Trash

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

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': Controls the base font size for the list and its children.
selectable boolean =false: Enables selection mode. Sets `role="listbox"` and manages `aria-selected` on child items.
multiple boolean =false: Allows multiple items to be selected simultaneously. Only applies when `selectable` is true.
value string ='': The currently selected value(s). Comma-separated when `multiple` is true.
label string ='': Accessible name for the list, applied as `aria-label`. Required when `selectable` is set so the listbox has an accessible name.

Events

arc-select detail: { value: string }: Fired from the activated arc-list-item when a selectable list is driven by Enter or Space.
arc-change detail: { value: string }: Fired when the selection changes. `event.detail.value` contains 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, links, and selection state.

value string ='': Unique identifier used for selection tracking.
selected boolean =false: Whether this item is currently selected. Managed automatically by the parent list.
disabled boolean =false: Prevents interaction and dims the item.
href string ='': When set, renders the item as an anchor tag for navigation.

List

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Events

List Item

See Also

Docs

Project

Arclight