# list

A short list of lines, each a title with an optional subtitle and link, read from a source or written as items.

Either `source` with the columns it shows (`title` required, `subtitle` and `href` optional), or `items`, 1 to 200
lines written in the YAML, each `{ title, subtitle, href }`. Exactly one of the two. An `href` is an `https://`
URL or a path starting with `/`. Lines show in the source's order; at most 200.

Category: data. Tier 1. Contract version 1.

## When to use

- A few things with one line each, such as the tools still rented and when they renew.
- Links a person needs next to the work, such as runbooks.
- The items of a "when to use" list on a reference screen.

## When to use another block

- Rows with several columns a person sorts or filters. Use [`grid`](/catalog/grid.md).
- Events in time order with who did them. Use [`timeline`](/catalog/timeline.md).
- One link that starts the next step. Use [`button`](/catalog/button.md).

## Props

- `id` (name: a-z, 0-9 and -): The block's id: its Markdown anchor and its actions' route (`/act/<id>/<action>`). Default `<type>-<n>`, n counting blocks of this type depth-first from 1.
- `source` (a source of the screen): The source whose rows are the lines (at most 200); or `items`.
- `title` (column): With `source`: the column holding each line's title (required with it).
- `subtitle` (column): With `source`: the column holding a line under it.
- `href` (column): With `source`: the column holding where each line links.
- `items` (list of 1–200: mapping): Written lines; or `source`.
  - `title` (text ≤ 200, required): The line's title.
  - `subtitle` (text ≤ 200): A line under it.
  - `href` (https:// URL or /path): Where the line links: an https:// URL or a path starting with /.

## Data

Reads the first 200 rows of `source`, when the lines are not written as items.

Shape: one row per line: a title column, optional subtitle and href columns.

## Actions

None: this block only shows.

## States

- **ready**: the source's rows, drawn
- **empty**: the source has no rows: an Empty part saying why and what comes next
- **error**: the source failed: "We couldn't load …" naming the block's rows, the source's sentence and Try again; the page still answers 200

## Examples

### Tools still rented

```yaml
list: { source: tools, title: name, subtitle: detail }
```

As an agent reads it:

```markdown
<a id="list-1"></a>

- Expense tool — Renews on 1 December
- Remote support seats — Renews on 15 January, 40 seats

```

### Runbooks, with links

```yaml
list: { source: runbooks, title: title, subtitle: team, href: url }
```

As an agent reads it:

```markdown
<a id="list-1"></a>

- [VPN profile reset](https://docs.example.com/runbooks/vpn) — Network
- [MFA reset on a new phone](https://docs.example.com/runbooks/mfa) — Identity

```

### Next steps, written in place

```yaml
list:
  items:
    - { title: Review the 27 tickets that need a person, href: /a/service-desk/queue }
    - { title: Retest the Apps agent on this week's tickets, subtitle: Hand-offs tripled since Monday }
```

As an agent reads it:

```markdown
<a id="list-1"></a>

- [Review the 27 tickets that need a person](/a/service-desk/queue)
- Retest the Apps agent on this week's tickets — Hand-offs tripled since Monday

```

## Invalid

```yaml
list:
  source: tools
  title: name
  items:
    - { title: Expense tool }
```

Answers: `list: write source (with title and its columns) or items, one of the two`

## Composition

- Sits in: screen, card, columns
- Pairs with: chart, card, heading
- Three to ten lines; past that a grid lets a person search.
- Apple HIG: Keep list items short and scannable, with the most important word first.

## Telemetry

list.view, list.open

JSON Schema: [/catalog/list.schema.json](/catalog/list.schema.json)