List — ARC UI

Components

List

data

interactive

<arc-list>

Overview

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

Use List for navigation menus — use `arc-navigation-menu` or `arc-dropdown-menu` instead
Mix arc-list-item with raw HTML elements inside a selectable list
Nest lists more than one level deep — consider a tree view for hierarchical data

Features

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';

<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: `
    <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>
  `,
})
export class MailboxComponent {}

import { List, ListItem, Icon, Badge } from '@arclux/arc-ui-solid';

<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';

<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

Prop	Type	Default	Description
`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.

Events

Event	Description
`arc-change`	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.

Prop	Type	Default	Description
`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.
`slot="prefix"`	`slot`	—	Leading content area for icons, avatars, or indicators.
`slot="suffix"`	`slot`	—	Trailing content area for badges, actions, or metadata.
`slot="description"`	`slot`	—	Secondary text rendered below the main label in smaller, muted type.