# columns

Puts two to four blocks side by side in equal shares, such as a chart and the events that explain it; they stack on a narrow screen.

`columns:` takes a list of 2 to 4 blocks directly, with no mapping and no `id`. Each child gets an equal share of
the width; under 900 px they stack top to bottom in the written order, so put the block a person needs first
first. There is no width or span: the theme decides spacing, the app decides only what sits next to what.

Category: layout. Tier 1. Contract version 1.

## When to use

- A chart and the timeline or list that explains it belong next to each other, such as hand-offs per hour beside the latest events.
- Two short things a person compares at a glance, such as what an agent may do and what it may not do.
- A form beside the note that says what happens after it is saved.

## When to use another block

- The blocks belong together under one title, such as a ticket's summary and its next step. Use [`card`](/catalog/card.md).
- Several single figures side by side, such as open tickets and median first reply. Use [`kpis`](/catalog/kpis.md).
- One table of many rows; it needs the full width of the screen. Use [`grid`](/catalog/grid.md).

## Props

The value is a list of 2 to 4 blocks, no mapping and no `id`.

## Data

Reads none.

Shape: none.

## Actions

None: this block only shows.

## States

- **ready**: always drawn; it reads no data

## Examples

### Hand-offs per hour beside the latest events

```yaml
columns:
  - chart: { title: Closed per hour today, kind: bar, source: hourly, x: hour, series: [closed, handed_off] }
  - timeline: { source: events, at: at, title: title, actor: actor, tone: tone }
```

As an agent reads it:

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

<a id="chart-1"></a>

**Closed per hour today** — bar chart, 3 points, hour 08:00 … 10:00

- closed: 31–52
- handed_off: 3–6

<a id="timeline-1"></a>

- 2026-10-31 09:12 · Opened by M. Okafor from the portal (portal)
- 2026-10-31 09:13 · Network agent pushed the corrected VPN profile (Network agent)
- 2026-10-31 09:20 · Requester confirmed the fix (M. Okafor)

```

### Where the money goes, beside the tools still rented

```yaml
columns:
  - chart: { title: Where the money goes this month, kind: donut, source: spend, x: category, series: [usd], format: usd }
  - list: { source: tools, title: name, subtitle: detail }
```

As an agent reads it:

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

<a id="chart-1"></a>

**Where the money goes this month** — donut chart, 3 points, category Agent results … People hours on tickets

- usd: $2,650–$6,140

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

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

```

### What an agent may and may not do

```yaml
columns:
  - markdown: { text: '**May do:** reset passwords, unlock accounts and send verified MFA reset links.' }
  - markdown: { text: "**May not do:** change a manager's access or anything in payroll; those go to a person." }
```

As an agent reads it:

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

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

**May do:** reset passwords, unlock accounts and send verified MFA reset links.

<a id="markdown-2"></a>

**May not do:** change a manager's access or anything in payroll; those go to a person.

```

## Invalid

```yaml
columns:
  - chart: { title: Closed per hour today, kind: bar, source: hourly, x: hour, series: [closed] }
```

Answers: `columns: write a list of 2 to 4 blocks (`columns:` takes no mapping)`

## Composition

- Sits in: screen, card
- Pairs with: chart, timeline, list, card
- Two columns read best; four only for short blocks such as small cards.
- Blocks of about the same height side by side; a tall one beside a short one leaves a hole.
- Apple HIG: Group related content side by side and let the layout adapt to the width available; never fix a width.

## Telemetry

columns.view

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