ListView

The ListView is a component for rendering a set of vertically stacked items. These items can be focusable, selectable, have one primary action and one or more secondary actions, and support keyboard navigation and accessibility features.

Usage

<script>
	import { ListView, ListViewItem } from 'fluentui-svelte';
	let list = ['A', 'B', 'C'];
	let selected = ['A'];
</script>

<ListView selectedItems={selected}>
	{#each list as item (item)}
		<ListViewItem value={item}>{item}</ListViewItem>
	{/each}
</ListView>

Navigation Mode

Use items to keep each item in the Tab order. Use composite to give the list one tab stop and enter an item's secondary controls with Right. Selection uses listbox and option roles in items mode, or grid, row and gridcell roles in composite mode. For selectable navigation with sublists, set role="list" on each ListView and use aria-current on links: each list manages its own selectedItems, without selecting items at other levels.

Best practices

• Keep lists that only display text out of the Tab sequence. Configure navigationMode on the outer ListView: use items for native link navigation and composite for selectable cards with secondary controls. Let the component manage item and control tabindex unless you opt out with disableTabspot.
• With the default grid roles in selectable composite lists, the component wraps each row's content in one gridcell and manages navigation to its controls. No manual gridcell wrappers are needed.
• Use onAction for an item's primary action and native buttons or links with onclick for secondary actions. Enter and Space both activate non-native actionable items; links retain native keyboard behavior. In composite selection rows, the checkmark changes selection independently, and secondary buttons and links do not trigger the row's action or selection.
• Keep the default roles for flat selection widgets; they depend on both selectionMode and navigationMode. Match the HTML tags: ul/ol with li items, or as="div" on both a card list and its items.
• Use ListViewItemBranch for expandable sublists. Branches are never selectable and manage their disclosure attributes and focus. Each nested list owns its selection. Set role="list" on each selectable list containing branches to preserve native list semantics.
• Give selectable ListView widgets an accessible name with aria-label or aria-labelledby. Give navigation a named nav landmark and mark the current link with aria-current="page". Use meaningful visible text or aria-label for controls, a descriptive branch label, and stable item value strings when using selection.

Keyboard navigation

Up and Down move between siblings; Home and End move to the ends of the current level. Right opens a collapsed branch; Right on an expanded branch enters its sublist. Left closes an expanded branch; Left on a collapsed branch or child returns to its parent. Escape closes the nearest branch and restores focus to its button. Right also enters a composite item's controls: Left and Right move between them, and Left from the first control returns to the row. Enter activates links; Enter and Space activate buttons and selectable items. In items mode, Tab visits the items and their controls; in composite mode, the entire list has one tab stop. disableTabspot opts out of arrow-key focus management.

Simple navigation

Wrap the list in a named nav landmark and use as="a" with href for navigation links. ListView wraps links in native list items when the list is a ul or ol. Use aria-current="page" on the current link; site navigation keeps native list and link semantics.

<nav aria-label="Main navigation">
  <ListView>
    <ListViewItem as="a" href="/">Home</ListViewItem>
    <ListViewItem as="a" href="/docs">Documentation</ListViewItem>
    <ListViewItem as="a" href="/docs/components/list-view" aria-current="page">ListView</ListViewItem>
  </ListView>
</nav>

Navigation with sublists

Nest a ListView inside ListViewItemBranch. Branches are focusable disclosure buttons and never selectable. Expanded state, aria-expanded, aria-controls, hidden content and focus restoration are managed automatically. Each nested list keeps its own selection state when collapsed. Use native list semantics; set role="list" when enabling selection on a list containing branches.

<script lang="ts">
  import { ListView, ListViewItem, ListViewItemBranch } from 'fluentui-svelte';
</script>

<nav aria-label="Component navigation">
  <ListView>
    <ListViewItem as="a" href="/">Home</ListViewItem>
    <ListViewItemBranch label="Components" expanded>
      <ListView>
        <ListViewItem as="a" href="/docs/components/button">Button</ListViewItem>
        <ListViewItemBranch label="Inputs" expanded>
          <ListView>
            <ListViewItem as="a" href="/docs/components/checkbox">Checkbox</ListViewItem>
            <ListViewItem as="a" href="/docs/components/radio-button">RadioButton</ListViewItem>
          </ListView>
        </ListViewItemBranch>
      </ListView>
    </ListViewItemBranch>
    <ListViewItem as="a" href="/docs">Documentation</ListViewItem>
  </ListView>
</nav>

Selection Mode

Use selectionMode (single, multiselect, or extended) to control how items are selected.

<ListView aria-label="Fruits" selectionMode="multiselect" selectedItems={['Apple']}>
  {#each ['Apple', 'Banana', 'Cherry'] as item (item)}
    <ListViewItem value={item}>{item}</ListViewItem>
  {/each}
</ListView>

Toggle on click

In a multiselect list, a plain click selects only that item and Ctrl/Cmd + click toggles it. Set toggleOnClick to make a plain click toggle the item directly.

<ListView aria-label="Fruits" selectionMode="multiselect" toggleOnClick>
  {#each ['Apple', 'Banana', 'Cherry'] as item (item)}
    <ListViewItem value={item}>{item}</ListViewItem>
  {/each}
</ListView>

Checkmark

Add and configure a checkbox for the element. You can use the same props for the Checkbox component.

The checkbox toggles the selection of its item without triggering onAction. Bind selectedItems to read or control the selection.

<script lang="ts">
  let selected = $state<string[]>(['Apple']);
</script>

<ListView aria-label="Fruits" selectionMode="multiselect" bind:selectedItems={selected}>
  {#each ['Apple', 'Banana', 'Cherry'] as item (item)}
    <ListViewItem value={item} checkmark={{}}>{item}</ListViewItem>
  {/each}
</ListView>

<p>Selected: {selected.join(', ')}</p>

Cards with a primary action

With navigationMode set to composite and a selectionMode, every item is a row. Set as="div" on both the list and its card items to keep the HTML structure valid. Clicking a row runs its primary action (onAction), the checkbox toggles its selection, and any button inside is a secondary action. Use checkmark.wrapperAttributes.style to place the checkbox where you need it, like the top-right corner of the card.

<script lang="ts">
  const cards = [
    { name: 'Fluent', description: 'Design system' },
    { name: 'Svelte', description: 'UI framework' },
    { name: 'Vite', description: 'Build tool' }
  ];

  let selected = $state<string[]>([]);
  let lastAction = $state('');
</script>

<ListView as="div" navigationMode="composite" selectionMode="multiselect" bind:selectedItems={selected}>
  {#each cards as card (card.name)}
    {#snippet install()}
      <Button
        onclick={() => {
          lastAction = 'Installed ' + card.name;
        }}>Install</Button
      >
    {/snippet}
    <ListViewItem
      as="div"
      value={card.name}
      checkmark={{ wrapperAttributes: { style: 'position: absolute; top: 0.5rem; right: 0.5rem; z-index: 2;' } }}
      style="padding: 0"
      onAction={() => (lastAction = 'Opened ' + card.name)}
    >
      <Card orientation="vertical" style="width: 100%;">
        <CardHeader title={card.name} description={card.description} />
        <CardFooter action={install} />
      </Card>
    </ListViewItem>
  {/each}
</ListView>

<p>Selected: {selected.join(', ')}</p>
<p>Last action: {lastAction}</p>

Secondary controls run their own actions without selecting the item or triggering its primary action. The checkbox only toggles selection.

ListView Props

ListViewItem Props

ListViewItemBranch Props