> ## Documentation Index
> Fetch the complete documentation index at: https://developers.reintersect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data components

> Badges, statuses, people, lists, metrics, tables, charts, images, files and references.

> Reintersect apps are in developer preview. Names and limits can still change before general
> release.

Data components take structured values: numbers, states and people. Reintersect formats the numbers,
picks colours and glyphs from the tone or state, and lays each list out on one shared grid.

## Badge

A short label, such as an issue label or a priority. Use it inline, in `Text`, `Header` or an
`Item`. A badge is one of three shapes: plain, toned, or with a colour swatch.

```tsx theme={null}
<Text>
  <Badge label="bug" swatch="#d73a4a" /> <Badge label="P1" tone="danger" />{" "}
  <Badge label="backend" icon="server" />
</Text>
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `label` | `string` | Yes | The badge text, up to 32 characters. |
| `tone` | `Tone` | No | Colour by meaning. A toned badge shows its tone's glyph. |
| `icon` | `IconName` | No | Shown before the label, on a neutral or untoned badge only. |
| `swatch` | `` `#${string}` `` | No | A label colour from your product, drawn as a dot on a neutral badge. It can't be combined with `tone` or `icon`. |

The types enforce the three shapes, so a toned badge with an `icon` is a type error. Long labels wrap
to two lines and show the full label in a tooltip.

## Status

A state, optionally with your own label. Use it to show where something stands, such as a build or a
ticket. It's inline, like `Badge`.

```tsx theme={null}
<Status state="running" label="Deploying" />
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `state` | `StatusState` | Yes | `neutral`, `queued`, `running`, `success`, `warning`, `failure`, `done`, `cancelled`, `skipped` or `blocked`. |
| `label` | `string` | No | Your wording for the state, up to 32 characters, such as "In review". Defaults to the state's own word. |

Each state has its own glyph and tone. Screen readers always hear the state's word, after your label
when it says something different, such as "Deploying, Running". Agent text reads
`Status: Deploying (Running)`.

## Person

A person's name with their avatar. Use it inline wherever a block names someone, such as an assignee.

```tsx theme={null}
<Text>
  Assigned to <Person name="Ada Lovelace" memberId="mem_123" />
</Text>
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Display name, up to 64 characters. |
| `memberId` | `string` | No | A Reintersect member id. The avatar and profile link come from the workspace. |
| `avatarSrc` | `string` | No | An `https://` image URL for people outside the workspace. Reintersect copies the image when the block is stored and never loads it from your host. |
| `href` | `string` | No | An `https://` link for the name. |

## MetaList and MetaItem

A single line of small details, separated by dots. Use it for secondary facts such as a branch, a
person and a start time.

```tsx theme={null}
<MetaList>
  <MetaItem icon="git-branch">main</MetaItem>
  <MetaItem icon="user">Ada</MetaItem>
  <MetaItem icon="clock">
    <Time datetime={startedAt} format="relative" />
  </MetaItem>
</MetaList>
```

| Prop | Component | Type | Required | Description |
| - | - | - | - | - |
| `children` | `MetaList` | `MetaItem` elements | Yes | One to six items. |
| `audience` | `MetaList` | `Audience` | No | Limit who sees the list. |
| `children` | `MetaItem` | JSX | Yes | Inline content, up to 60 characters of text. |
| `icon` | `MetaItem` | `IconName` | No | Shown before the item. |

Reintersect draws the `·` between items. Agent text joins the items the same way.

## Facts and Fact

Label and value pairs. Use them to list the fields of a record, such as a ticket.

```tsx theme={null}
<Facts>
  <Fact label="Customer">Acme Inc.</Fact>
  <Fact label="Plan">Business</Fact>
  <Fact label="Renews">
    <Time datetime="2026-12-01" format="date" />
  </Fact>
</Facts>
```

| Prop | Component | Type | Required | Description |
| - | - | - | - | - |
| `children` | `Facts` | `Fact` elements | Yes | The pairs. Labels are unique within the list. |
| `audience` | `Facts` | `Audience` | No | Limit who sees them. |
| `label` | `Fact` | `string` | Yes | The field name, up to 32 characters. |
| `children` | `Fact` | JSX | Yes | The value, as inline content, up to 120 characters of text. |

Every label in a list shares one column. When the list is narrower than 320px, each label moves
above its value. Agent text has one `Label: value` line per fact.

## Metrics and Metric

Headline numbers, each with an optional change and trend line. Use them for measurements such as
latency, an error rate or revenue. You pass the number and how to format it, and Reintersect writes
it out in the viewer's locale.

```tsx theme={null}
<Metrics>
  <Metric label="p95 latency" value={182} format="duration" delta={{ value: -12, goodWhen: "down" }} />
  <Metric
    label="Error rate"
    value={0.004} // 0.4%: percent values are fractions
    format="percent"
    delta={{ value: -0.001, goodWhen: "down" }} // −0.1%
    trend={[0.009, 0.007, 0.006, 0.005, 0.004]}
  />
  <Metric
    label="Revenue"
    value={18402}
    format="currency"
    currency="EUR"
    delta={{ value: 0.08, percent: true, goodWhen: "up" }} // +8% change
  />
  <Metric label="Queue depth" value={18402} unit="jobs" />
</Metrics>
```

| Prop | Component | Type | Required | Description |
| - | - | - | - | - |
| `children` | `Metrics` | `Metric` elements | Yes | One to six metrics. Labels are unique within the group. |
| `audience` | `Metrics` | `Audience` | No | Limit who sees them. |
| `label` | `Metric` | `string` | Yes | What's measured, up to 32 characters. |
| `value` | `Metric` | `number` | Yes | The current value, as a finite number. |
| `format` | `Metric` | `NumberFormat` | No | `number` (default), `percent`, `currency`, `duration` or `bytes`. |
| `unit` | `Metric` | `string` | No | Up to 12 characters, such as `"jobs"`. Plain numbers only. |
| `currency` | `Metric` | `string` | With `"currency"` | A three-letter ISO code, such as `"EUR"`. Only with `format: "currency"`. |
| `delta` | `Metric` | `MetricDelta` | No | The change since the last period: `{ value, percent?, goodWhen? }`. |
| `trend` | `Metric` | `number[]` | No | 2 to 24 finite points for a sparkline. |

How each format reads:

| `format` | `value` means | Example |
| - | - | - |
| `number` | The number itself, with an optional `unit` | `18402` with `unit: "jobs"` reads "18,402 jobs" |
| `percent` | A fraction | `0.08` reads "8%" |
| `currency` | An amount in `currency` | `18402` with `currency: "EUR"` reads "€18,402" in English |
| `duration` | Milliseconds | `252000` reads "4m 12s" |
| `bytes` | Bytes, in base 1,000 | `18400000` reads "18.4 MB" |

A delta takes the metric's format, so a latency delta of `-12` reads "−12ms". With `percent: true`
it reads as a percent change instead, and its value is a fraction too: `0.08` is +8%. `goodWhen`
says which direction is good. Reintersect derives the sign, the arrow, the colour and the spoken
text from that: a fall in latency with `goodWhen: "down"` is green and read as "Down 12ms, better".
Without `goodWhen`, a delta is neutral.

Values of a million or more are compacted, such as `1.2M`, with the exact value in the tooltip and the
accessible text. The value never truncates: the sparkline drops below it first, then the number gets
a step smaller, then it wraps. Reintersect picks the number of columns from the number of metrics,
in balanced rows: four go two by two and five go three and two.

Agent text has one `Label: value (delta)` line per metric, such as `Error rate: 0.4% (−0.1%)`.

## Progress

A progress bar with its text worked out for you. Use it to show how far along something is, such as
a rollout across regions.

```tsx theme={null}
<Progress label="Rollout" value={3} max={8} unit="regions" />
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `value` | `number` | Yes | Current value, from 0 to `max`. |
| `max` | `number` | No | Default `100`. |
| `unit` | `string` | No | Up to 12 characters. Needs `max`. |
| `label` | `string` | No | What's progressing, up to 60 characters. Default "Progress" in agent text. |
| `audience` | `Audience` | No | Limit who sees it. |

Progress takes a value out of `max`, not a fraction. Without `max`, the value is out of 100 and the
text is the percentage, such as "40%". With `max`, the text reads "3 of 8 regions", and screen
readers hear the percentage too: "3 of 8 regions, 38%". Agent text reads
`Rollout: 3 of 8 regions (38%)`.

## AvatarStack

A row of overlapping avatars. Use it to show a group of people, such as reviewers or attendees.

```tsx theme={null}
<AvatarStack
  label="Reviewers"
  people={[{ name: "Ada Lovelace", memberId: "mem_123" }, { name: "Grace Hopper" }]}
/>
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `people` | `PersonSpec[]` | Yes | 1 to 50 people, each `{ name, memberId?, avatarSrc?, href? }` as on `Person`. |
| `label` | `string` | No | What the group is, up to 60 characters. Default "People" in agent text. |
| `audience` | `Audience` | No | Limit who sees it. |

Reintersect shows up to five avatars. The rest sit behind a **+N** button that opens the full list,
with each person's name, avatar and link.

## ItemList and Item

A list of rows, each with a title, an optional description and content before and after it. Use it
for a list of objects, such as the pull requests in a release.

```tsx theme={null}
<ItemList>
  <Item
    href="https://github.com/acme/web/pull/42"
    leading={<Icon name="git-pull-request" />}
    description="Ada · 3 files"
    trailing={<Status state="success" label="Merged" />}
  >
    Add the export button
  </Item>
</ItemList>
```

| Prop | Component | Type | Required | Description |
| - | - | - | - | - |
| `children` | `ItemList` | `Item` elements | Yes | The rows. |
| `audience` | `ItemList` | `Audience` | No | Limit who sees the list. |
| `children` | `Item` | JSX | Yes | The row title, up to 80 characters. |
| `href` | `Item` | `string` | No | An `https://` link for the row. |
| `leading` | `Item` | JSX | No | One `Icon`, `Person` or `Status`, drawn as a single glyph. |
| `description` | `Item` | JSX | No | A second line, up to 280 characters. It clamps after three lines with **Show more**. |
| `trailing` | `Item` | JSX | No | One or two of `Status`, `Badge`, `Time` and `Duration`, or plain text of up to 24 characters. |

Every row in a list shares one grid, so titles start at the same edge. When the list is narrower
than 320px, trailing content moves under the title. A linked row shows a small arrow. Agent text has
one `- ` line per item, with its parts joined by `·`.

## Steps and Step

An ordered list of stages, each with a state. Use it to show progress through a sequence, such as a
deployment pipeline.

```tsx theme={null}
<Steps>
  <Step label="Build" state="success" />
  <Step label="Staging" state="running" description="Smoke tests" />
  <Step label="Production" state="queued" />
</Steps>
```

| Prop | Component | Type | Required | Description |
| - | - | - | - | - |
| `children` | `Steps` | `Step` elements | Yes | The stages, in order. |
| `audience` | `Steps` | `Audience` | No | Limit who sees them. |
| `label` | `Step` | `string` | Yes | The stage name, up to 80 characters. |
| `state` | `Step` | `StatusState` | Yes | Where the stage is. |
| `description` | `Step` | `string` | No | A detail line, up to 280 characters. It clamps after three lines with **Show more**. |

Agent text has one entry per step, such as `Build (Succeeded)`.

## Table

Rows of typed cells. Use it for data with several columns, such as failing checks with their status
and owner. Reintersect handles the header, sorting, paging, number formatting and alignment, and the
layout on narrow screens.

```tsx theme={null}
<Table
  label="Failing checks"
  pageSize={10}
  columns={[
    { key: "check", label: "Check", kind: "text" },
    { key: "status", label: "Status", kind: "status" },
    { key: "owner", label: "Owner", kind: "person" },
    { key: "duration", label: "Duration", kind: "number", format: "duration", sortable: true },
    { key: "passRate", label: "Pass rate", kind: "number", format: "percent" },
  ]}
  rows={[
    {
      key: "lint",
      href: "https://ci.example.com/runs/42/lint",
      cells: {
        check: "lint",
        status: { state: "failure" },
        owner: { name: "Ada Lovelace", memberId: "mem_123" },
        duration: 184000,
        passRate: 0.92, // 92%: percent values are fractions
      },
    },
  ]}
/>
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `label` | `string` | Yes | An accessible name for the table, up to 80 characters. |
| `columns` | `TableColumn[]` | Yes | 1 to 12 columns: `{ key, label, kind, sortable? }`, plus `format`, `unit` and `currency` on number columns. Labels are up to 24 characters and unique. |
| `rows` | `TableRow[]` | Yes | Up to 200 rows: `{ key, cells, href?, menu? }`. |
| `pageSize` | `10 \| 25 \| 50` | No | Rows per page in the browser. |
| `audience` | `Audience` | No | Limit who sees it. |

Cell values follow the column `kind`, and the types check them:

| Kind | Cell value |
| - | - |
| `text` | `string`, at most 280 characters. Long text clamps after three lines with **Show more**. |
| `number` | `number`, formatted by the column's `format`, `unit` and `currency` like a [`Metric`](#metrics-and-metric) |
| `status` | `{ state, label? }` |
| `person` | `{ name, memberId?, avatarSrc?, href? }` |
| `time` | `string \| Date` |
| `badge` | `{ label, tone? }` |
| `link` | `{ label, href }`, with a label of up to 60 characters |

Number columns are aligned to the end; everything else starts at the beginning. Only number columns
take `format`, `unit` or `currency`.

A table narrower than 400px becomes a list of cards, so nothing scrolls sideways. The first column
is each card's title, the other columns become label and value pairs in column order, and empty
cells are left out. The row link wraps the title and the row menu sits at the card's top right. A
table with sortable columns gets a **Sort** menu, and sorting and paging carry over to the cards.

A row `menu` takes up to 12 items with the same shape as [`MenuItem`](/components/interactive#menu)
props, so each row can run actions. Agent text has the table as Markdown rows.

## Chart

A small bar, line, area or donut chart. Use it to show values over time or a breakdown, such as
deploys per day.

```tsx theme={null}
<Chart
  kind="bar"
  title="Deploys per day"
  unit="deploys"
  series={[
    {
      name: "Production",
      points: [
        { label: "Mon", value: 4 },
        { label: "Tue", value: 7 },
        { label: "Wed", value: 3 },
      ],
    },
  ]}
/>
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `kind` | `"bar" \| "line" \| "area" \| "donut"` | Yes | Chart type. |
| `title` | `string` | Yes | What the chart shows, up to 80 characters. |
| `format` | `NumberFormat` | No | How values read on the axis, in tooltips and in the data table, as on [`Metric`](#metrics-and-metric). |
| `unit`, `currency` | `string` | No | As on `Metric`: `unit` for plain numbers, `currency` with `format: "currency"`. |
| `series` | `ChartSeries[]` | Yes | 1 to 3 series of 1 to 24 finite points each. Series names and the point labels in a series are up to 24 characters and unique. Every series uses the same point labels in the same order. |
| `audience` | `Audience` | No | Limit who sees it. |

With `format: "percent"`, chart values are fractions too:

```tsx theme={null}
<Chart
  kind="line"
  title="Checkout conversion"
  format="percent"
  series={[
    {
      name: "Conversion",
      points: [
        { label: "Week 1", value: 0.031 }, // 3.1%
        { label: "Week 2", value: 0.034 }, // 3.4%
        { label: "Week 3", value: 0.042 }, // 4.2%
      ],
    },
  ]}
/>
```

A donut has one series of at most five slices, with no negative values and a total above zero. When
two or more slices are under 2% of the total, they merge into one "Other" slice. A chart whose values
are all zero shows a quiet "No values yet." line instead of an empty plot.

Reintersect picks the colours and draws each series with its own dash and marker, so series never
differ by shade alone. Axis ticks are rounded and compacted, long point labels are cut to fit with
the full label in the tooltip, and **Show data** opens the exact values as a table for keyboard and
screen reader users. Agent text has the chart's data as a table.

## Image

An image from an `https://` URL. Use it to show a screenshot or another picture inside the block.

```tsx theme={null}
<Image src="https://cdn.example.com/screens/checkout.png" alt="The new checkout page" aspect="16:9" size="md" />
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `src` | `string` | Yes | An `https://` URL. |
| `alt` | `string` | Yes, unless `decorative` | Describes the image, up to 200 characters. |
| `decorative` | `true` | No | Marks the image as decoration; then `alt` isn't allowed. |
| `aspect` | `"1:1" \| "4:3" \| "16:9" \| "auto"` | No | Default `"auto"`. |
| `size` | `"thumb" \| "sm" \| "md" \| "full"` | No | Default `"md"`. |
| `audience` | `Audience` | No | Limit who sees it. |

With `aspect: "auto"`, the image keeps its own shape between 1:2 (tall) and 3:1 (wide), and is
never shorter than 48px. A `thumb` is always square. The frame fits the image, with no letterbox.

When a block is stored, Reintersect downloads each image once and serves its own copy, so viewers
never load your host. Images must be JPEG, PNG, WebP or GIF, at most 5 MB and at most 8,192 pixels on
each side, and must download within 4 seconds. A block holds at most 10 images. If an image can't be
copied, Reintersect shows its `alt` text as muted text instead, or nothing for a decorative image;
the rest of the block still renders.

## File

A link to a file, with its name, size and type. Use it for a download, such as a report.

```tsx theme={null}
<File
  name="q3-report.pdf"
  href="https://files.example.com/q3-report.pdf"
  sizeBytes={482133}
  mimeType="application/pdf"
/>
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | The file name, up to 120 characters. |
| `href` | `string` | Yes | An `https://` download link. Reintersect doesn't copy files. |
| `sizeBytes` | `number` | No | Shown in a readable unit, such as "482.1 kB". |
| `mimeType` | `string` | No | Picks the type tag, such as "PDF". |
| `audience` | `Audience` | No | Limit who sees it. |

The type tag comes from `mimeType`, then from a known file extension in `name`. Files of other types
show no tag.

## Reference

A link that Reintersect renders the way it renders any pasted link: as a chip, a card or a plain link.
Use it to point to an object, such as a pull request, a video or one of your app's own records. Links
your app claims render with your reference's fields, and links to providers Reintersect supports,
such as GitHub or YouTube, render with theirs.

```tsx theme={null}
<Reference url="https://github.com/acme/web/pull/42" display="chip" />
```

| Prop | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | An `https://` URL. |
| `display` | `"chip" \| "block" \| "link"` | No | Default `"chip"`. |
| `audience` | `Audience` | No | Limit who sees it. |

Reintersect treats `display` as a preference. A `"block"` shows as a card only when the provider has
a card for the link and its data is ready. Otherwise it shows as a chip. See
[References](/references/overview).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.