Data Display

DescriptionList

Renders an ordered set of term and value pairs that describe attributes of a single entity.

import { DescriptionList } from '@lostgradient/cinder';
metadatakey-value
01

Overview

Reference usage

Semantic dl/dt/dd list for term–description pairs such as metadata or attributes.

Usage

svelte 
<script lang="ts">
  import { DescriptionList } from '@lostgradient/cinder';
  import type { DescriptionListItem } from '@lostgradient/cinder';

  const items: DescriptionListItem[] = [
    { term: 'Component', definition: 'DescriptionList' },
    { term: 'Status', definition: 'Stable' },
    { term: 'Version', definition: '1.0.0' },
    { term: 'License', definition: 'MIT' },
    { term: 'Maintainer', definition: 'Cinder team' },
  ];
</script>

<DescriptionList {items} />

The two-column variant sets a muted term on the left and the value on the right, with no row dividers.

Formatted values

A definition can be a value the list formats, so every list shows timestamps, IDs and tags the same way:

  • { type: 'timestamp', value }: a readable date and time, with the exact time (full date, seconds and zone) on hover.
  • { type: 'identifier', value }: an ID or hash, shortened and set in small monospace, with an icon-only copy button that copies the whole value.
  • { type: 'tags', tags, systemTagCount, onAddTag }: read-only tags, with system tags counted instead of listed and an Add a tag action that calls onAddTag.
svelte 
<script lang="ts">
  import { DescriptionList } from '@lostgradient/cinder';
  import type { DescriptionListItem } from '@lostgradient/cinder';

  const items: DescriptionListItem[] = [
    {
      term: 'Run ID',
      definition: { type: 'identifier', value: '3f2b9c1a-7d4e-4a86-9b0c-1e5d6f7a8b90' },
    },
    { term: 'Started', definition: { type: 'timestamp', value: '2026-10-30T14:15:07Z' } },
    {
      term: 'Tags',
      definition: {
        type: 'tags',
        tags: ['billing', 'nightly'],
        systemTagCount: 3,
        onAddTag: () => console.log('add a tag'),
      },
    },
  ];
</script>

<DescriptionList {items} variant="two-column" />
Live preview

Description list

Component
DescriptionList
Status
Stable
Version
1.0.0
License
MIT
Maintainer
Cinder team

02

When to use

Use when
  • Summarizing the properties of one record such as a user profile or order detail.
  • Switching between stacked and inline term layouts via the variant prop.
Avoid when
  • Iterating over a homogenous collection of records — use data-list or table instead.
03

Examples

Description list

Key–value metadata pairs in the default stacked layout.

Description list rich definitions

Definitions can render rich snippet content when plain text is not enough.

Description list variants

Striped and two-column layout variants.

04

Props

Props for description-list
Name
Type
Default
Description
items required DescriptionListItem[]
variant 'default' | 'striped' | 'two-column' | 'narrow' 'default' Controls the visual layout: - default: stacked rows with visible terms. - striped: alternating row backgrounds. - two-column: a muted term on the left and the value on the right, with no row dividers; collapses to stacked at narrow widths. - narrow: <dt> is visually hidden via .cinder-sr-only. Only appropriate when surrounding context already labels the value. NOT a general compact mode.
stack boolean false Puts every term above its value at any width. The two-column variant already stacks once its own container is narrower than 28rem; stack stacks it regardless, for a list whose page has already chosen its phone layout. Has no effect on narrow, whose terms stay visually hidden.
actions snippet Optional snippet rendered once per row. Receives the full DescriptionListItem so consumers can build disambiguated aria-label strings (e.g. aria-label="Edit ${item.term}"). Any interactive element in actions MUST set an unambiguous aria-label.