Data Display

GroupedList

Inset group of rows on one rounded surface with inset separators, a header and footer outside the surface, and an optional quick-add first row.

import { GroupedList } from '@lostgradient/cinder';
listgroup
01

Overview

Reference usage

GroupedList is an inset group: one rounded surface that holds its rows, a header and footer outside the surface, and an optional quick-add first row (a leading accent "+", a borderless input, and Return to submit). Rows are GroupedListItem elements, whose separators start at the text.

Usage

svelte 
<script lang="ts">
  import { GroupedList, GroupedListItem } from '@lostgradient/cinder';
</script>

<GroupedList header="Wi-Fi" footer="Known networks join automatically.">
  <GroupedListItem href="/settings/home">
    {#snippet title()}Home{/snippet}
    {#snippet subtitle()}Connected{/snippet}
  </GroupedListItem>
  <GroupedListItem href="/settings/office">
    {#snippet title()}Office{/snippet}
  </GroupedListItem>
</GroupedList>
Live preview

Rows on one rounded surface

Wi-Fi

Known networks join automatically.

02

When to use

Use when
  • Listing related rows, such as settings, people or places, as one grouped surface instead of a stack of boxed cards.
  • Adding items inline with a first row that takes text and submits on Return.
Avoid when
  • Rows need a status column, details or a disclosure — use data-list with stacked-list-item.
  • Comparing values across columns — use table.
03

Examples

Rows on one rounded surface

The header and footer sit outside the group, rows are linked as a whole, and separators start at the text.

A lead column and a fixed action column

The lead column and the action column have fixed widths, so a longer value in one row never moves another row or a click target.

A quick-add first row

A leading accent plus and a borderless input. Return submits the text to onItemAdd and clears the input.

04

Props

Props for grouped-list
Name
Type
Default
Description
header text A header drawn above the group, outside its surface, in small muted text. It also names the list.
footer text A note drawn under the group, outside its surface, in small muted text.
children snippet The rows: GroupedListItem elements.
onItemAdd (value: string) => void Adds a quick-add first row: a leading accent "+" and a borderless input. Return submits the trimmed text here and clears the input; an empty entry is ignored.
addLabel text 'Add an item' Accessible name of the quick-add input.
addPlaceholder text Placeholder text of the quick-add input. Left unset, it shows the label.