# Heading

> Section headings with a semantic level and an independent visual size.

Category: Typography · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/heading

Choose `level` to match the document outline and `size` to match the visual hierarchy. Keeping them separate lets a card title be an h3 that looks small, or a hero be an h1 at display size, without breaking the outline screen-reader users navigate by.

## Import

```tsx
import { Heading } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Heading } from '@bindshq/stance-react';

export function Basic() {
  return <Heading level={2}>Organisation templates</Heading>;
}
```

### Size scale

```tsx
import { Heading, Stack } from '@bindshq/stance-react';

export function Scale() {
  return (
    <Stack gap={3}>
      {(['display', '3xl', '2xl', 'xl', 'lg', 'md', 'sm'] as const).map((s) => (
        <Heading key={s} level={3} size={s}>
          {s} · One system
        </Heading>
      ))}
    </Stack>
  );
}
```

### Level vs size

```tsx
import { Heading, Stack, Text } from '@bindshq/stance-react';

export function Decoupled() {
  return (
    <Stack gap={1}>
      <Text eyebrow>Contracts</Text>
      <Heading level={2} size="2xl">
        Master services agreement
      </Heading>
      <Heading level={3} size="md" tone="muted" weight="medium">
        Acme Ltd · Draft v3
      </Heading>
    </Stack>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Heading | `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Semantic level (h1 to h6). |
| Heading | `size` | `'display' \| '3xl' \| '2xl' \| 'xl' \| 'lg' \| 'md' \| 'sm'` | None | Visual size. Defaults by level. |
| Heading | `as` | `'h1'…'h6' \| 'p' \| 'span' \| 'div' \| 'legend'` | None | Override the rendered element. |
| Heading | `weight` | `'medium' \| 'semibold' \| 'bold'` | `'semibold'` | Font weight. |
| Heading | `align` | `'start' \| 'center' \| 'end'` | None | Text alignment. |
| Heading | `tone` | `'default' \| 'muted'` | `'default'` | Colour. |
| Heading | `balance` | `boolean` | `true` | Balance multi-line headings. |

## Accessibility

- Keep one h1 per page and do not skip levels. Screen-reader users navigate by heading.
- Display and 3xl sizes scale fluidly with clamp() and respect browser zoom.

## Guidelines

**Do**

- Write headings that describe the content below.
- Use sentence case.

**Don’t**

- Pick a level for its size; use size.

## Related

- https://stanceui.com/components/text
- https://stanceui.com/components/rich-text