Descriptions

Demo & usage

More examples

<sv-descriptions
  layout="vertical"
  [columns]="3"
  [items]="[
    { id: 'sku',   label: 'SKU',   value: 'ORD-4182' },
    { id: 'total', label: 'Total', value: '$248.00' },
    { id: 'notes', label: 'Notes', value: 'Leave with the concierge.', span: 3 },
  ]" />

<sv-descriptions
  [items]="order()?.fields ?? []"
  [loading]="pending()"
  [error]="failure()"
  (retry)="reload()" />

<sv-descriptions [items]="details">
  <ng-template svDescriptionAction let-item>
    <button type="button"
            [attr.aria-label]="'Copy ' + item.label"
            (click)="copy(item)">Copy</button>
  </ng-template>
</sv-descriptions>

<sv-descriptions [items]="details" stackAt="md" />
<sv-descriptions [items]="shortLabels" stackAt="never" />

When to use

• The read-only half of a record page — view order, user profile, resource detail, invoice header.
• Any place a grid of hand-rolled <span> pairs is standing in for a description list.
• For editable fields use a Form; for many records at once use a Data Table.

Async states

• loading
• empty
• error
• retry

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 — drive it from whatever you already use.

<sv-descriptions
  [items]="data.items()"
  [loading]="data.loading()"
  [error]="data.error()"
  (retry)="data.reload()"
/>

// This component reports its state but does not emit a query, so drive
// it from your own fetch and bind the three async inputs.
readonly items = signal<Row[]>([]);
readonly loading = signal(false);
readonly error = signal<SvDataError | null>(null);

async load(): Promise<void> {
  this.loading.set(true);
  this.error.set(null);
  try {
    this.items.set(await this.api.fetchRows());
  } catch (e) {
    this.error.set(toSvDataError(e));
  } finally {
    this.loading.set(false);
  }
}

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `items`, `loading` and `error`.
• 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

• `svDiffValues()` from `@styloviz/core` turns two records into a list of changed paths, which maps straight onto `DescriptionItem[]` for a before/after view — the same engine Code Block and JSON Viewer use, rather than a fourth one.
• Lay out with `layout` (horizontal / vertical), `columns` (1–4, stepping down on narrow viewports) and a per-item `span` that is clamped to the row width.
• Choose a surface with `variant` (plain / bordered) and a scale with `size` (sm / md / lg).
• Set `emptyValueText` for the missing-value placeholder, and `valueClass` per item (e.g. `font-mono` for an ID).
• Full async contract: `loading`, `error`, `emptyText` and a `retry` output.
• `<ng-template svDescriptionAction let-item>` adds one action per row, rendered as its own column inside the definition and given the item so the action can name the term it acts on.
• `stackAt` (`never` / `sm` / `md` / `lg`) sets where a horizontal pair stops sitting side by side and stacks.

Best practices

• Do: Send `null` for a field you do not have and `''` for one that is genuinely blank — they render differently on purpose.
• Do: Give a long value its own row with `span` rather than letting it squeeze the column.
• Tip: Pass `title` so the list gets an accessible name; it is wired to `aria-labelledby` for you.
• Don't: Don't use it for a collection of records — it describes one.
• Do: Name a row action with the term it acts on — `'Copy ' + item.label`. Inside a definition, "Copy" on its own tells a listener nothing about what is being copied.
• Don't: Don't put a second list, a form control or a group of buttons inside a value. A `<dl>` is a flat sequence of pairs, and nesting turns the reading into a depth-first walk nobody can predict. One action per row is what the slot is sized for.
• Tip: Reach for `stackAt="never"` only with short labels. Two columns on a 320px screen leave the value about eleven characters, and a truncated value is worse than a stacked one.

Accessibility

• Renders a real `<dl>` with one `<dt>`/`<dd>` pair per item, each wrapped in a `<div>` — valid HTML5 that keeps the pairing screen readers announce.
• A `title` becomes an `<h3>` and names the list via `aria-labelledby`; ids are instance-scoped, so two lists on one page never collide.
• No `aria-labelledby` is emitted without a heading, so the fallback name is never suppressed.
• A missing value shows a dimmed placeholder rather than an empty cell that reads as a rendering bug.
• A row action is rendered inside its `<dd>` because HTML permits no sibling there, so it becomes part of what the definition reads as — which is why the docs insist its accessible name carries the term. It is laid out as a separate column so the value text keeps its alignment.
• A stacked pair gets real vertical spacing, so a label and its value do not read as one wrapped sentence on a narrow screen.