# Heading

A themeable heading with `size` and `color` from the typography scale. Renders an `h2` unless `level` says otherwise. `HeadingLevelProvider` sets the level for headings nested below it.

## Use for

- a section or page title
- a heading whose level follows its nesting, with `HeadingLevelProvider` and `useHeadingLevel`

## Practices

- Do: Pass `level={useHeadingLevel()}` from a component rendered inside the `HeadingLevelProvider` when the heading should follow its nesting. `Heading` does not read the level from context on its own.
- Do: Wrap a nested region in `HeadingLevelProvider` so headings inside it sit one level deeper.
- Don't: Pick `level` for its look. Use `size` for the look and `level` for the outline.

## API reference

### Heading

Renders `h1` to `h6` and forwards its ref. Defaults can come from `HeadingContext`.

Slot: `cl-heading`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `TypographySize` | `'base'` | Type scale step. |
| `color` | `TypographyColor` | `'foreground'` | Text color token. |
| `level` | `HeadingLevel` | `2` | The heading element, `1` to `6`. |

### HeadingLevelProvider

Sets the level `useHeadingLevel` returns below it. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `level` | `HeadingLevel` | `` one below the parent's, capped at `6`; the root is `2` `` | The level for its subtree. |

## Examples

### A nested heading

```tsx
function SectionHeading({ children }: { children: React.ReactNode }) {
  return <Heading level={useHeadingLevel()}>{children}</Heading>;
}

<HeadingLevelProvider>
  <SectionHeading>Members</SectionHeading>
</HeadingLevelProvider>
```

## Related

- [Panel](/docs/components/panel.md)
- [Text](/docs/components/text.md)
