> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# Heading

Geist for titles and section headings, where hierarchy comes from the size step — reach for `Text` when the words are copy rather than a title. Visual size and document level are independent: pick `size` for how it looks and `as` for the outline, so a visually small heading can still be the `h2` the structure needs.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/Heading) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/typography-heading--overview)

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';

export const Basic = () => (
  <Heading>Default Heading</Heading>
);
```

## Usage

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';
```

## Examples

### Sizes

The full ramp with its metrics. The bottom steps deliberately duplicate the text ramp — `sm`
is 14 on 20 exactly as in `Text` — because what separates them is semantic, not visual.

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';
import { VStack } from '@wallarm-org/design-system/Stack';
import { Text } from '@wallarm-org/design-system/Text';

export const Sizes = () => (
  <VStack gap={24} align='start'>
    {SIZES.map(({ size, metrics }) => (
      <VStack key={size} gap={4} align='start'>
        <Text size='xs' color='secondary'>
          size=&apos;{size}&apos; · {metrics}
        </Text>
        <Heading size={size}>
          The quick brown fox
        </Heading>
      </VStack>
    ))}
  </VStack>
);
```

### Weights

All four weights at every size, so weight emphasises within a level rather than creating one.

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';
import { VStack } from '@wallarm-org/design-system/Stack';

export const Weights = () => (
  <VStack align='start'>
    <Heading size='3xl' weight='light'>
      Light Weight Heading
    </Heading>
    <Heading size='3xl' weight='regular'>
      Regular Weight Heading
    </Heading>
    <Heading size='3xl' weight='medium'>
      Medium Weight Heading
    </Heading>
    <Heading size='3xl' weight='bold'>
      Bold Weight Heading
    </Heading>
  </VStack>
);
```

### As child

`asChild` moves the styling onto your own element, keeping whatever tag the surrounding
markup needs.

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';

export const AsChild = () => (
  <Heading size='4xl' weight='bold' asChild>
    <h2>Custom H2 Element with AsChild</h2>
  </Heading>
);
```

### Polymorphic elements

`as` across the heading levels, which is the outline both a screen reader and a table of
contents read. Choose it from the document structure, not from the size you wanted.

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';
import { VStack } from '@wallarm-org/design-system/Stack';

export const PolymorphicElements = () => (
  <VStack align='start'>
    <Heading as='h1' size='4xl'>
      H1 Heading
    </Heading>
    <Heading as='h2' size='3xl'>
      H2 Heading
    </Heading>
    <Heading as='h3' size='2xl'>
      H3 Heading
    </Heading>
    <Heading as='h4' size='xl'>
      H4 Heading
    </Heading>
    <Heading as='h5' size='lg'>
      H5 Heading
    </Heading>
    <Heading as='h6' size='md'>
      H6 Heading
    </Heading>
  </VStack>
);
```

### As span

A heading rendered inline, for a title inside a row of other content where a block element
would break the line.

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';
import { Text } from '@wallarm-org/design-system/Text';

export const AsSpan = () => (
  <Text>
    This is a paragraph with{' '}
    <Heading as='span' size='lg' weight='bold'>
      inline heading text
    </Heading>{' '}
    using span element.
  </Text>
);
```

### As div

A heading with no document level at all, for text that looks like a title but should not
appear in the outline.

```tsx
import { Heading } from '@wallarm-org/design-system/Heading';

export const AsDiv = () => (
  <Heading as='div' size='2xl' weight='medium'>
    This heading is rendered as a div element
  </Heading>
);
```

## Props

| Prop        | Type                                                                                                                                            | Default   | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
| color       | `{ primary: string; 'primary-alt': string; secondary: string; 'secondary-alt': string; inherit: string; }`                                      | `inherit` |             |
| size        | `{ sm: string; md: string; lg: string; xl: string; '2xl': string; '3xl': string; '4xl': string; '5xl': string; '6xl': string; '7xl': string; }` | `xl`      |             |
| weight      | `{ light: string; regular: string; medium: string; bold: string; }`                                                                             | `bold`    |             |
| align       | `{ left: string; center: string; right: string; }`                                                                                              |           |             |
| grow        | `{ true: string; }`                                                                                                                             | `false`   |             |
| truncate    | `{ true: string; }`                                                                                                                             | `false`   |             |
| asChild     | `boolean \| undefined`                                                                                                                          | `false`   |             |
| lineClamp   | `number \| undefined`                                                                                                                           |           |             |
| data-testid | `string \| undefined`                                                                                                                           |           |             |
| as          | `C \| undefined`                                                                                                                                | `h1`      |             |