# Text

Headings, running text and feedback messages. The intent decides the element (`<h1>`, `<p>`, `<span>`, `<pre>`) and the look.

Renders: `h1` `h2` `h3` `p` `span` `div` `blockquote` `summary` `code` `pre` · Intents: [37](#intents-it-renders) · Domains: [`heading.*`](https://www.prongs.dev/docs/intents/heading.md) [`text.*`](https://www.prongs.dev/docs/intents/text.md) [`feedback.*`](https://www.prongs.dev/docs/intents/feedback.md)

## Examples

### A page title

A kicker names the section, the page heading is the one `<h1>`, and the lead introduces the page.

```tsx
<Layout intent="layout.group">
  <Text intent="heading.kicker">Settings</Text>
  <Text intent="heading.page">Notifications</Text>
  <Text intent="text.lead">Choose what we email you about, and how often.</Text>
</Layout>
```

### An item and its facts

Facts about one thing go in [`text.meta`](https://www.prongs.dev/docs/intents/text/meta.md), side by side in a [`layout.meta`](https://www.prongs.dev/docs/intents/layout/meta.md).

```tsx
<Layout intent="layout.group">
  <Text intent="heading.item">Quarterly report</Text>
  <Layout intent="layout.meta">
    <Text intent="text.meta">PDF</Text>
    <Text intent="text.meta">2.4 MB</Text>
    <Text intent="text.meta">Updated 3 days ago</Text>
  </Layout>
  <Text intent="text.excerpt">Revenue grew in every region, led by new customers in the north.</Text>
</Layout>
```

### Messages

[`feedback.*`](https://www.prongs.dev/docs/intents/feedback.md) intents are announced to screen readers: errors at once, the rest politely.

```tsx
<Layout intent="layout.group">
  <Text intent="feedback.success">Your changes were saved.</Text>
  <Text intent="feedback.error">That address is already taken.</Text>
</Layout>
```

### Figures

A headline number is [`text.stat`](https://www.prongs.dev/docs/intents/text/stat.md); the words that name it are [`text.label`](https://www.prongs.dev/docs/intents/text/label.md).

```tsx
<Layout intent="layout.collection" className="grid-cols-3">
  <Layout intent="layout.group">
    <Text intent="text.stat">12</Text>
    <Text intent="text.label">Projects</Text>
  </Layout>
  <Layout intent="layout.group">
    <Text intent="text.stat">4</Text>
    <Text intent="text.label">Members</Text>
  </Layout>
  <Layout intent="layout.group">
    <Text intent="text.stat">2.1 GB</Text>
    <Text intent="text.label">Storage</Text>
  </Layout>
</Layout>
```

## Intents it renders

3 domains, each with its own page of neighbours and examples. The intent decides the element; these are the starter intents.

### Heading [`heading.*`](https://www.prongs.dev/docs/intents/heading.md)

6 intents

| Intent | Use it for | Resolves to |
|---|---|---|
| [`heading.pitch`](https://www.prongs.dev/docs/intents/heading/pitch.md) | The persuasive headline of a marketing page: what the product does for you | `<h1>` |
| [`heading.page`](https://www.prongs.dev/docs/intents/heading/page.md) | The one title of a page: Settings, Sign in, Privacy policy, a profile name | `<h1>` |
| [`heading.section`](https://www.prongs.dev/docs/intents/heading/section.md) | Title of a major part of a page | `<h2>` |
| [`heading.item`](https://www.prongs.dev/docs/intents/heading/item.md) | Title of a single thing: a list item, a panel, a dialog. A link in it keeps the heading colour | `<h3>` |
| [`heading.side`](https://www.prongs.dev/docs/intents/heading/side.md) | The name of one side in a side-by-side comparison: With intents, Without. A step smaller than heading.item, so it reads as a label over what is compared | `<h3>` |
| [`heading.kicker`](https://www.prongs.dev/docs/intents/heading/kicker.md) | A short label above a heading that names its category | `<p>` |

### Text [`text.*`](https://www.prongs.dev/docs/intents/text.md)

27 intents

| Intent | Use it for | Resolves to |
|---|---|---|
| [`text.body`](https://www.prongs.dev/docs/intents/text/body.md) | Running text: sentences and paragraphs that explain something | `<p>` |
| [`text.lead`](https://www.prongs.dev/docs/intents/text/lead.md) | Introductory paragraph directly under a page or section title | `<p>` |
| [`text.caption`](https://www.prongs.dev/docs/intents/text/caption.md) | A supporting sentence next to something else: helper text under a field, a note under an image | `<p>` |
| [`text.label`](https://www.prongs.dev/docs/intents/text/label.md) | A few words that name a value: field labels, setting names, column headers. Use as="label" htmlFor=... for form fields | `<span>` |
| [`text.current`](https://www.prongs.dev/docs/intents/text/current.md) | The page you are on, named at the end of a breadcrumb trail. Not a link. Pass aria-current="page" | `<span>` |
| [`text.term`](https://www.prongs.dev/docs/intents/text/term.md) | The name of a fact, above its value in a layout.fact: Profile, Status, Raised with | `<p>` |
| [`text.value`](https://www.prongs.dev/docs/intents/text/value.md) | The value of a fact, under its text.term. A value that links somewhere goes in a text.topic; plain words do not | `<div>` |
| [`text.meta`](https://www.prongs.dev/docs/intents/text/meta.md) | Small facts about an item: timestamps, authors, @handles, file sizes | `<span>` |
| [`text.quote`](https://www.prongs.dev/docs/intents/text/quote.md) | Words quoted from someone, set apart from the text around them: a pull quote in an article, a testimonial. Renders <blockquote> | `<blockquote>` |
| [`text.excerpt`](https://www.prongs.dev/docs/intents/text/excerpt.md) | A short extract of a longer text, shown as a preview: an article summary | `<p>` |
| [`text.topic`](https://www.prongs.dev/docs/intents/text/topic.md) | Names a topic or category an item belongs to: News, Science. Sits one surface level above what holds it. A link inside it covers the whole chip; without one, a link covering its item covers the chip too | `<span>` |
| [`text.status`](https://www.prongs.dev/docs/intents/text/status.md) | The state something is in, as a word in an outlined pill: Flying, Charging, On time. data-tone="success", "info", "pending", "warning", "danger" or "muted" colours it | `<span>` |
| [`text.count`](https://www.prongs.dev/docs/intents/text/count.md) | A number that sums something up: unread notifications, items waiting | `<span>` |
| [`text.indicator`](https://www.prongs.dev/docs/intents/text/indicator.md) | A dot that marks something as new or unread, or shows a status, with no number. Give it an aria-label, like "Unread" or "Charging"; data-tone="success", "info", "warning", "danger" or "muted" colours a status; data-busy makes it pulse while something is in progress | `<span>` |
| [`text.summary`](https://www.prongs.dev/docs/intents/text/summary.md) | The line that stays visible in a layout.disclosure; pressing it opens or closes the content | `<summary>` |
| [`text.line`](https://www.prongs.dev/docs/intents/text/line.md) | One line in an agent terminal; data-kind says what it is: "ask" for the person (or "prompt", set as a chat bubble), "skip" for a step that turned up nothing useful and "keep" for one that found what was wanted, "agent" for its reply, "step" for something it did, "run" for a check still running, "fail" for one that failed, "pass" for one that passed. Steps lead with an icon, and any output follows in a text.output | `<div>` |
| [`text.output`](https://www.prongs.dev/docs/intents/text/output.md) | The message a step in an agent terminal produced, such as what a check found, set under the step behind a thin rule. Code inside it goes in a text.snippet | `<span>` |
| [`text.diff`](https://www.prongs.dev/docs/intents/text/diff.md) | The change a step in an agent terminal made to a file: its removed and added lines, each a text.diff.line | `<div>` |
| [`text.diff.line`](https://www.prongs.dev/docs/intents/text/diff-line.md) | One line of a text.diff; data-change="add" or "remove" marks and tints it | `<span>` |
| [`text.token`](https://www.prongs.dev/docs/intents/text/token.md) | A highlighted piece of code; data-token names it: "tag", "attr", "string" or "punct" | `<span>` |
| [`text.snippet`](https://www.prongs.dev/docs/intents/text/snippet.md) | A short piece of code inside a sentence: an element, an intent, a command | `<code>` |
| [`text.tally`](https://www.prongs.dev/docs/intents/text/tally.md) | The number in a layout.tally.item, counting up as the work it measures happens | `<span>` |
| [`text.delta`](https://www.prongs.dev/docs/intents/text/delta.md) | How a number differs from the one it is compared with, beside it, like −74%: data-tone="good" or "bad" colours it by whether the change is an improvement; with no data-tone it stays hidden | `<span>` |
| [`text.marker`](https://www.prongs.dev/docs/intents/text/marker.md) | The label an inspector shows on the element it points at: its intent. Starts at the element's left edge, or its right edge when the layout.marker has data-align="end" | `<span>` |
| [`text.stat`](https://www.prongs.dev/docs/intents/text/stat.md) | A headline number on its own: a metric, a result, a price | `<p>` |
| [`text.code`](https://www.prongs.dev/docs/intents/text/code.md) | A block of code or terminal output shown to the reader | `<pre>` |
| [`text.address`](https://www.prongs.dev/docs/intents/text/address.md) | The address in a layout.window.bar | `<span>` |

### Feedback [`feedback.*`](https://www.prongs.dev/docs/intents/feedback.md)

4 intents

| Intent | Use it for | Resolves to |
|---|---|---|
| [`feedback.error`](https://www.prongs.dev/docs/intents/feedback/error.md) | Something failed or input is invalid. Announced to screen readers immediately | `<p>` |
| [`feedback.warning`](https://www.prongs.dev/docs/intents/feedback/warning.md) | Something may go wrong unless the user acts | `<p>` |
| [`feedback.success`](https://www.prongs.dev/docs/intents/feedback/success.md) | An action the user took worked | `<p>` |
| [`feedback.info`](https://www.prongs.dev/docs/intents/feedback/info.md) | A neutral status about the current state: loading, searching, nothing to show yet | `<p>` |

## Props

Plus its element’s usual attributes (`id`, `onClick`, `aria-*`, `data-*`) and the shared layout props below. No `className` or `style`.

| Prop | Type | What it does |
|---|---|---|
| `intent` (required) | `TextIntent` | What this text is for: [`heading.*`](https://www.prongs.dev/docs/intents/heading.md), [`text.*`](https://www.prongs.dev/docs/intents/text.md) or [`feedback.*`](https://www.prongs.dev/docs/intents/feedback.md). |
| `as` | `'h1'…'h6' \| 'p' \| 'span' \| 'div' \| 'label'` | Changes the element for document structure only, like `as="label"` for a field label or `as="h2"` for a dialog title. The intent still decides the look. |
| `htmlFor` | `string` | With `as="label"`: the `id` of the field it labels. |
| `vars` | `Record<`--${string}`, string \| number>` | Values that come from data, as CSS variables the intent reads: `vars={{ '--accent': user.color }}`. |
| `unsafeClassName` | `string` | Bypasses the intent. Needs a `// prongs-unsafe: <reason>` comment on the line above, and `prongs check` counts it. |

### Layout props

Where the element sits, never how it looks. Spacing between elements comes from the parent [`<Layout>`](https://www.prongs.dev/docs/components/layout.md).

| Prop | Type | What it does |
|---|---|---|
| `align` | `'start' \| 'center' \| 'end'` | On text, the text alignment. On anything else, pushes it to that end of its row or column. |
| `width` | `'auto' \| 'full' \| 'prose' \| 'sm' \| 'md' \| 'lg'` | Full width, or a maximum width. |
| `hideBelow` | `'sm' \| 'md' \| 'lg'` | Hidden on screens narrower than this breakpoint. |
| `showBelow` | `'sm' \| 'md' \| 'lg'` | Shown only on screens narrower than this breakpoint. |
| `truncate` | `boolean` | One line, cut off with an ellipsis. |
| `nowrap` | `boolean` | Keeps the text on one line. |

## Rules

- No `className` or `style`. If text needs to look different, it is a different intent.
- Use `as` only to fix document structure, never to change the look.
- Emphasis inside a sentence is plain `<strong>` or `<em>`, not another [`<Text>`](https://www.prongs.dev/docs/components/text.md).