List View

Demo & usage

More examples

<sv-list-view [items]="items" [grouped]="true" [searchable]="true" [stickyGroupHeaders]="true" />

<sv-list-view
  [items]="items"
  [virtualized]="true"
  [infiniteScroll]="true"
  [hasMore]="hasMore"
  (loadMore)="fetchNext()" />

<sv-list-view
  [items]="items"
  [virtualized]="true"
  [(activeItemId)]="cursorId"
  [(scrollOffset)]="scrollTop" />

<sv-list-view
  [items]="items"
  [grouped]="true"
  [checkable]="true"
  [(checkedIds)]="checkedIds" />

When to use

• Rendering feeds, checklists, contacts or any vertical collection of items.
• You need grouping, quick/bulk actions, or virtualization for long lists.
• For tabular, column-aligned data use Data Table.

Async states

• loading
• empty
• error
• retry
• partial

Item identity & owned state

Restorable state

• checkedIds
• expandedIds
• selectedIds
• selectionChange

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Outputs

<sv-list-view-pro>

Also in this family — SvListViewProComponent from @styloviz-pro/list-view.

Inputs

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — it just saves you writing the debounce, the request guard and the retry policy by hand.

<sv-list-view
  [serverSide]="true"
  [items]="data.items()"
  [loading]="data.loading()"
  [error]="data.error()"
  [hasMore]="data.hasMore()"
  (queryChange)="data.setQuery($event)"
  (retry)="data.reload()"
/>

import { svDataController, createHttpDataSource } from '@styloviz/data';

readonly data = svDataController(
  createHttpDataSource<Row>({ url: '/api/rows' }),
);

• `queryChange` carries an `SvDataQuery` — page, page size, sorts, filters, search and cursor in one object. One handler covers every way the user can change what they are asking for.
• `serverSide` switches **off** the built-in filtering, sorting and paging. Leave it false and the component works entirely from the array you pass — which is what you want for a few hundred rows.
• `debounceMs` (default 300) collapses a burst of typing into one request. Set it to 0 only when the query is driven by clicks.
• `hasMore` and `loadMore` drive incremental paging; bind `hasMore` from the controller's own signal of the same name.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Swap between flat, grouped, checklist and card layouts.
• Virtualization keeps long lists fast.
• Quick actions and bulk actions per row.
• Every mode renders the same row: avatar, badge, trailing amount, quick actions and the selection control are present under `virtualized` and `grouped` too, not only on a flat list.
• `[(activeItemId)]` is the keyboard cursor and `[(scrollOffset)]` the scroll position — both two-way, so a host can deep-link to a row, restore either after a route change, or read back where the user left off.
• **Feature compatibility.** Row presets (`default`, `checklist`, `template`, `call-history`) compose with everything. The structural ones do not: `virtualization` windows flat lists only, `grouped` renders every section in full, and `nested` renders the tree in full and beats `grouped`.
• Under `virtualized`, a row's height is computed from `itemHeight` plus a line for a `subtitle`/`description` and a strip for `tags`, and the row is then sized to that number — so the scrollbar and the rows always agree.

Best practices

• Do: Enable `virtualized` for lists beyond a few hundred items.
• Do: Pair `infiniteScroll` with `hasMore`/`loadingMore` so the end state is clear.
• Do: Bind `[(activeItemId)]` and `[(scrollOffset)]` on any list a user can navigate away from and come back to. Restoring the rows alone puts them back at the top of the list with no keyboard cursor.
• Do: Set `itemHeight` to the height of a **single-line** row under `virtualized`. Rows with a `subtitle`, a `description` or `tags` are measured taller automatically; setting the tallest row's height as the base leaves gaps under every short row instead.
• Tip: Use `grouped` with `stickyGroupHeaders` to keep context while scrolling.
• Don't: Don't combine `virtualized` with `nested` or `grouped`, or `nested` with `grouped` — one wins and the other silently does nothing. Each ignored pair logs a dev-mode warning naming what to drop.

Accessibility

• Keyboard at scale (X-10): the list is ONE tab stop however many rows it holds — the region around the rows is not a second one. ↑/↓ move a row and stop at the ends, Home/End jump to them, PageUp/PageDown move one viewport of rows and clamp (they never wrap), and typing a few letters moves to the next row whose title starts with them. Documented ceiling: 2,000 rendered rows (`SV_UNVIRTUALIZED_ROW_CEILING`) — above it, turn on `virtualized` (flat lists); a nested or grouped list past it warns once in dev mode.
• Rows are keyboard navigable (roving focus with arrow keys, Home/End) and have clear focus.
• Under `virtualized` the cursor walks the whole list, not the rendered window: ArrowDown past the last visible row scrolls the next one in, and End reaches the true last row. Exactly one row is a tab stop, so Tab enters and leaves the list once.
• Scrolling the focused row out of the window moves focus to the scroller rather than losing it to the page, and the next arrow key carries on from the row the cursor was on.
• Each row declares `aria-posinset`/`aria-setsize` — against the whole list when windowed, against its own section when grouped — so a screen reader announces "row 140 of 241" rather than the size of the window.
• A grouped, checkable list gives each section header a checkbox that reports `indeterminate` as "mixed" while the section is partly checked; disabled rows are left out of it.
• A nested list publishes its shape rather than drawing it: depth reached the page as `padding-left` alone, so every branch read as one flat pile. Each row is now a `listitem` carrying `aria-level` and an `aria-posinset`/`aria-setsize` counted against its own siblings, and each expander carries `aria-expanded` plus a label naming the branch ("Collapse src"), not a generic "Expand node".
• A paged list says where it ends. The footer used to disappear on the last page, so "the data ends here" and "the next page is slow" looked identical; it now holds an end marker naming the total, and the live region speaks each page arriving ("Loaded 20 more items.") and the list running out ("End of list. All 241 items loaded."). A list that arrives already complete stays silent — nothing happened.
• Quick/bulk action buttons and per-row selection controls are individually labelled.
• The search field is labelled; selection changes are announced via a polite live region.