---
title: Heading
description: Use the heading component to render title or subtitle text.
keywords: ['title', 'subtitle']
ready: true
figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=354%3A8982'
source: https://github.com/primer/brand/blob/main/packages/react/src/Heading/Heading.tsx
storybook: '/brand/storybook/?path=/story/components-heading--playground'
---

```js
import {Heading} from '@primer/react-brand'
```

## Examples

### Default

```jsx
<Heading>This is my super sweet heading</Heading>
```

### Scale

```jsx
<Stack gap="condensed" style={{width: '100%'}}>
  <Heading size="display">Display: 96px</Heading>
  <Heading size="1">1: 72px</Heading>
  <Heading size="2">2: 64px</Heading>
  <Heading size="3">3: 48px</Heading>
  <Heading size="4">4: 40px</Heading>
  <Heading size="5">5: 32px</Heading>
  <Heading size="6">6: 24px</Heading>
  <Heading size="subhead-large">subhead-large: 20px</Heading>
  <Heading size="subhead-medium">subhead-medium: 16px</Heading>
</Stack>
```

### Levels

The `Heading` level can be assigned using the `as` prop, which accepts any valid HTML heading tag.

Its visual appearance corresponds to the `1-6` scale values, but can be overridden using the `size` prop.

```jsx
<Stack gap="condensed" style={{width: '100%'}}>
  <Heading as="h6">This is my super sweet heading as a h6</Heading>

  <Heading as="h2" size="4">
    This h2 will appear visually identical to a h4
  </Heading>
</Stack>
```

### Weight

The recommended text weight is automatically applied to Headings based on their position on the type scale.

Use the `weight` prop to override the default visual appearance if required.

```jsx
<Stack gap="condensed" style={{width: '100%'}}>
  <Heading as="h3" weight="heavy">
    heavy
  </Heading>
  <Heading as="h3" weight="extrabold">
    extrabold
  </Heading>
  <Heading as="h3" weight="bold">
    bold
  </Heading>
  <Heading as="h3" weight="semibold">
    semibold
  </Heading>
  <Heading as="h3" weight="medium">
    medium
  </Heading>
  <Heading as="h3" weight="normal">
    normal
  </Heading>
  <Heading as="h3" weight="light">
    light
  </Heading>

  {/* Responsive */}
  <br />
  <br />
  <Heading
    as="h4"
    weight={{
      narrow: 'heavy',
      regular: 'semibold',
      wide: 'light',
    }}
  >
    Responsive
  </Heading>
</Stack>
```

### Width / Stretch

The recommended text width value is automatically applied to Headings based on their position on the type scale.

Use the `stretch` prop to override the default visual appearance if required.

```jsx
<Stack gap="condensed" style={{width: '100%'}}>
  <Heading as="h3" stretch="condensed">
    condensed
  </Heading>
  <Heading as="h3" stretch="normal">
    normal
  </Heading>
  <Heading as="h3" stretch="expanded">
    expanded
  </Heading>

  {/* Responsive */}
  <br />
  <br />
  <Heading
    as="h4"
    stretch={{
      narrow: 'condensed',
      regular: 'normal',
      wide: 'expanded',
    }}
  >
    Responsive
  </Heading>
</Stack>
```

### Letter spacing

The recommended character letter spacing is automatically applied to Headings based on their position on the type scale.

Use the `letterSpacing` prop to override the default settings if required.

```jsx
<Stack gap="condensed" style={{width: '100%'}}>
  <Heading as="h3" letterSpacing="condensed">
    condensed
  </Heading>
  <Heading as="h3" letterSpacing="normal">
    normal
  </Heading>
  <Heading as="h3" letterSpacing="none">
    none
  </Heading>

  {/* Responsive */}
  <br />
  <br />
  <Heading
    as="h4"
    letterSpacing={{
      narrow: 'condensed',
      regular: 'normal',
      wide: 'none',
    }}
  >
    Responsive
  </Heading>
</Stack>
```

## Component props

### Heading

| Name            | Type                                                    |       Default       | Description                                    |
| :-------------- | :------------------------------------------------------ | :-----------------: | :--------------------------------------------- |
| `as`            | `HeadingTags`                                           | `defaultHeadingTag` | Applies the underlying HTML element            |
| `className`     | `string`                                                |                     | Sets a custom class on the root element        |
| `id`            | `string`                                                |                     | Sets a custom id                               |
| `ref`           | `React.RefObject`                                       |                     | Forward a Ref to the underlying DOM node       |
| `size`          | `HeadingSizes`                                          |                     | Override the default visual text size          |
| `weight`        | `HeadingWeights \| 'ResponsiveWeightMap'`               |                     | Override the default visual text weight        |
| `stretch`       | `HeadingStretch \| 'ResponsiveStretchMap'`              |                     | Override the default visual text stretch value |
| `letterSpacing` | `HeadingLetterSpacing \| 'ResponsiveLetterSpacingMap'`> |                     | Override the default visual character spacing  |