Data Display

GroupedListItem

Row of a grouped list with leading icon, avatar, thumbnail or control, a fixed lead column, title, subtitle, and trailing value, photo, chevron and action; the whole row is the link.

import { GroupedListItem } from '@lostgradient/cinder';
listrow
01

Overview

Reference usage

GroupedListItem is one row of a GroupedList. It has a leading slot (an icon, a 40 to 72px thumbnail, an avatar or a checkbox), a fixed lead column for a time or number, a title, a subtitle, a trailing photo, a trailing value, a chevron and an action. With href the whole row is the link, and rows have hover and selected fills. The action sits in a fixed-width column, so a badge or value never moves the click target. A status is a small dot plus a word in the subtitle.

Usage

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

<GroupedList header="Runs">
  <GroupedListItem href="/runs/1">
    {#snippet lead()}45 min left{/snippet}
    {#snippet title()}Nightly backup{/snippet}
    {#snippet subtitle()}Running{/snippet}
  </GroupedListItem>
</GroupedList>

Time-led rows

Pass leadValue and leadUnit instead of a lead snippet for a row led by time, such as a happy hour or a run that is about to start. The lead is a fixed 72px column, right-aligned, with a 24px tabular number and a 12px unit. The unit comes from a closed vocabulary: min left, left, min to go, starts, or a weekday (Mon to Sun). A range of times never goes in the lead; put it in the subtitle. urgency="urgent" draws the lead in the warning text colour and urgency="soon" mutes it. The name is 17px and wraps; the subtitle is 15px and muted, one line per item. A trailing value carries a distance or other meta. staleAge draws a gray clock and a short age, and only when the row is stale. A trailing photo is a 56px column at the end of the row and reserves no space when absent.

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

<GroupedList header="Open now">
  <GroupedListItem href="/places/rooftop" leadValue={45} leadUnit="min left" urgency="urgent">
    {#snippet title()}The Rooftop{/snippet}
    {#snippet subtitle()}Half-price wells{/snippet}
    {#snippet trailing()}0.4 mi{/snippet}
  </GroupedListItem>
</GroupedList>

Suggested rows

suggested marks a row the product drafted that is not saved until the person confirms it. The row says so in words: a quiet "Suggested" label in the accent text colour on a line above the title, which suggestedLabel can change, for example to "Suggested wording". The row keeps its own surface: no tint, no dashed or accent border and no pill.

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

<GroupedList header="Next actions">
  <GroupedListItem suggested>
    {#snippet title()}Call the landlord about the lease{/snippet}
    {#snippet subtitle()}Drafted from your note{/snippet}
  </GroupedListItem>
</GroupedList>
Live preview

Leading slots

People

02

When to use

Use when
  • Listing entities inside a grouped list, each with a leading glyph, a title and a secondary line.
  • Linking each row to a detail view by passing href, which makes the whole row one link.
Avoid when
  • Showing a status-first run or approval row with details — use stacked-list-item.
  • Comparing values across columns — use table.
03

Examples

Leading slots

The leading slot holds an icon, an avatar, a 56px thumbnail or a control, each sized for its kind.

Time-led rows

A fixed 72px lead holds a number and a unit from a closed vocabulary. Urgent uses the warning text colour, soon is muted, and a stale row draws a gray clock and a short age.

04

Props

Props for grouped-list-item
Name
Type
Default
Description
title required snippet The row's main text. With href, it becomes the link and the whole row is its target.
subtitle snippet A secondary line under the title, in muted text. A status is a small dot plus a word here, never a badge.
leading snippet A leading icon, thumbnail, avatar or control, drawn before the text.
leadingKind 'icon' | 'avatar' | 'media' | 'control' 'icon' What the leading slot holds.
lead snippet A fixed-width column for a time or number, such as "45 min left", drawn before the title. Rows in one list line up.
leadValue text The number or word of a time-led row's lead, such as 45 or 9:30, drawn large. Pair it with leadUnit. Ignored when a lead snippet is given. A range of times never goes here.
leadUnit 'min left''left''min to go''starts''Mon''Tue''Wed''Thu'
3 more members 'Fri''Sat''Sun'
 The small unit under the lead number, from a closed vocabulary. Used with leadValue.
urgency 'urgent' | 'soon' How pressing the lead is. urgent uses the warning text colour and soon is muted; left unset, the lead uses the default text colour. Used with leadValue.
staleAge text A short age, such as 3d, drawn with a gray clock before the trailing value. Give it only when the row's information is stale; a fresh row draws no marker.
photo snippet A trailing 56px photo. It reserves no space when absent.
trailing snippet A trailing value, such as a count or a short status. It is right-aligned and never moves the action column.
action snippet A trailing action such as a menu button. It sits in a fixed-width column, so a changing value never moves its click target.
chevron boolean Draws a trailing chevron. Left unset, a row with href draws one.
selected boolean false Marks the row as the current one with a tint.
suggested boolean false Marks the row as a suggestion that is not saved until the person confirms it: a quiet accent text label on a line above the title, with no tint, border or pill.
suggestedLabel text 'Suggested' The words of the suggested label, such as "Suggested wording". Used with suggested.
href text Makes the whole row a link to this address.
target text Where to open the link.
rel text The link's relationship; noopener noreferrer is added for _blank.