<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

# Heading

A section title, `<h1>` to `<h6>`, in the theme's foreground color. `level` sets the tag and a default size; `size` changes only the look.

```tsx
import { Heading } from "@/components/ouro/text/heading";
```

## Example

```tsx
<Heading level={1}>Recipes</Heading>
<Heading level={2} size="lg">Ingredients</Heading>
<Heading level={1} size="display">Dinner, sorted</Heading>
```

## Use instead when

- Use `Text` instead for body copy, and for a dialog or sheet title use its `title` prop, which also labels it for assistive technology.

## Props

Type: `HeadingProps`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `"start" \| "center" \| "end"` | inherited | Alignment in writing direction. |
| `children` (required) | `ReactNode` |  | The heading text. |
| `className` | `string` |  | Layout only: margins, width, grid placement (`mb-2`). Appearance classes warn in development; use `size` and `align`. |
| `level` (required) | `1 \| 2 \| 3 \| 4 \| 5 \| 6` |  | Outline level: sets the tag (`level={2}` renders `<h2>`). Required, because the level is about document structure, not looks; use `size` to change how big it looks. |
| `ref` | `Ref<HTMLHeadingElement>` |  | Reaches the rendered element. |
| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "display"` | derived from `level` (1 is `2xl`, 2 is `xl`, 3 is `lg`, 4 is `md`, 5 and 6 are `sm`) | Visual size, independent of the level. `display` is the hero headline of a landing page, tightly set and larger from the `sm` breakpoint: `<Heading level={1} size="display">`. |

## Native attributes

Also accepts the attributes in React's `HTMLAttributes` (`id`, `aria-*`, event handlers), passed to the rendered element, except those named on this page.

## Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

- `as`: Not a prop. The tag comes from `level`: `<Heading level={2}>`.
- `color`: Not a prop. Headings use the theme's foreground color; for colored text use `<Text tone="…">`.

## `className` is for layout only

Pass margins, width and grid placement (`mt-4`, `w-full`, `col-span-2`).

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (`hover:`, `sm:`) and any `!` are removed, it starts with `bg-`, `text-`, `border-`, `rounded-`, `shadow-`, `font-`, `ring-`, `from-`, `via-`, `to-`, `fill-` or `stroke-`, or is `border`, `rounded`, `shadow` or `ring`, or has a `dark:` variant. Text wrapping, overflow and table layout classes (`text-wrap`, `text-ellipsis`, `border-collapse`) are layout and do not warn.

Alignment classes (`text-center`) warn too: use the `align` prop.
