---
title: Headings
description: >-
version: 11.17.0
generatedAt: 2026-11-05T09:55:46.981Z
checksum: 3800f13f6cc6734878db13a6613c635526ec29a25b1efacb53b7fdb4efb9e915
---

# Headings

## Import

```tsx
import { Heading } from '@dnb/eufemia/components'
import { H1, H2, H3, H4, H5, H6 } from '@dnb/eufemia/elements'
```

## Description

Eufemia comes with three levels of heading styles:

- `.dnb-h--xx-large` (Heading xx-large)
- `.dnb-h--x-large` (Heading x-large)
- `.dnb-h--large` (Heading large)

Additionally, you can use these style modifiers if needed:

- `.dnb-h--medium`
- `.dnb-h--basis`
- `.dnb-h--small`
- `.dnb-h--x-small`

Optionally, you can use `.dnb-lead` (equivalent to `.dnb-h--medium`) to style a heading as well, but only if that makes sense in the particular context.

The sizes are aligned to the [font-size definitions](/web/layout-and-typography/typography/font-size).

## Font family

DNB headings use DNB Sans Text by default. Display is **experimental**;
[contact the Eufemia team](/about/contact) before using it. Use `family="display"` on
`H1`–`H6` or `Heading` for a short, expressive headline. The
heading level and font size remain independent of the family. See
[font roles and Display examples](/web/layout-and-typography/typography/#display-headlines).

## Relevant links

- [Source code](https://github.com/dnbexperience/eufemia/tree/main/packages/dnb-eufemia/src/elements/typography)
- [Docs code](https://github.com/dnbexperience/eufemia/tree/main/packages/dnb-design-system-portal/src/docs/web/layout-and-typography/elements/heading)

## Think semantics first

You should [think semantics first](/web/development-guidelines/for-typography#headings-and-styling) when choosing what level of heading you use. Always try to start with an `<h1>`. When the heading levels are properly defined, you can go ahead and define the sizes (styles).

If you have to use a paragraph (`<p>`) or an arbitrary heading, and it has to **look like** a specific heading, you can use these classes:

- `.dnb-h--xx-large`
- `.dnb-h--x-large`
- `.dnb-h--large`
- etc.

Read more about [best practices for typography](/web/development-guidelines/for-typography).

## Automated heading levels

There is also [Heading](/web/components/heading), a component to create automated semantic headings within a boundary of some rules.

```jsx
import { Heading } from '@dnb/eufemia/components'
```

## Heading styles in React

```jsx
import { H1, H2, ... } from '@dnb/eufemia'
```


## Demos

### The most basic use of headings

Just using the `H1, H2, etc.` components will give you the basic headings.


```tsx
<H1>Heading 1</H1>
<H2>Heading 2</H2>
<H3>Heading 3</H3>
<H4>Heading 4</H4>
<H5>Heading 5</H5>
<H6>Heading 6</H6>
<P>Regular text</P>
```


### Prose max width

The `proseMaxWidth` property allows you to limit the width of heading text based on character count, creating optimal reading line lengths:


```tsx
<H4>
    This is a regular heading without any width constraints. It will
    extend to the full width of its container.
  </H4>
<H4 proseMaxWidth={40}>
    This heading uses proseMaxWidth={40} to limit its width to
    approximately 40 characters.
  </H4>
<H4 proseMaxWidth={20}>
    This heading uses proseMaxWidth={20} for an even narrower reading
    width.
  </H4>
<H4 proseMaxWidth>
    This heading uses proseMaxWidth with its default value.
  </H4>
```


#### Using Typography.Context

Use `Typography.Context` to apply `proseMaxWidth` to multiple headings at once:


```tsx
render(<Typography.Context proseMaxWidth={40}>
        <H4>
          This heading is inside a Typography.Context with proseMaxWidth=
          {40}
        </H4>
        <H4 proseMaxWidth={20}>
          This heading overrides the provider with proseMaxWidth={20}
        </H4>
      </Typography.Context>)
```


### Heading typography using React JSX

The visual size of a heading can be customized using the `size` property with values: `xx-large | x-large | large | medium | basis | small | x-small`


```tsx
<H1>Heading 1 (default size 'xx-large')</H1>
<H1 size="x-large">Heading 1 style 'x-large'</H1>
<H1 size="small">Heading 1 style small</H1>
```


By using the `<small>` element, we decrease the size one level (default size is `xx-large`):


```tsx
<H1 size="x-large">Heading style x-large (using 'size')</H1>
<H1>
    <small>Heading style x-large (using &lt;small&gt;)</small>
  </H1>
```


## Heading styles in vanilla HTML


```tsx
<h1 className="dnb-h--xx-large">Heading style xx-large</h1>
<h2 className="dnb-h--x-large">Heading style x-large</h2>
<h3 className="dnb-h--large">Heading style large</h3>
<h3 className="dnb-h--small">Heading style small</h3>
<h3 className="dnb-h--basis">Heading style basis</h3>
```


### Additional Heading modifiers


```tsx
render(<article>
      <h1 className="dnb-h--xx-large">
        .dnb-h--xx-large <small>small</small>
      </h1>
      <h2 className="dnb-h--x-large">
        .dnb-h--x-large <small>small</small>
      </h2>
      <h2 className="dnb-h--large">
        .dnb-h--large <small>small</small>
      </h2>
      <h3 className="dnb-h--medium">
        .dnb-h--medium <small>small</small>
      </h3>
      <h3 className="dnb-lead">
        .dnb-lead <small>small</small>
      </h3>
    </article>)
```


### Example of margin collapsing

Only the largest margin takes effect.


```tsx
<H4 size="small" top bottom="small">
    Spacing with bottom margin: small
  </H4>
<P top="large" bottom="small">
    Spacing with top margin: large
  </P>
```


### Dark surface

Use [Section](/web/components/section/demos/#dark-surface) or [Theme.Context](/web/styling-and-themes/brands-and-dark-mode/theme#surface-property) with `surface="dark"` to provide dark surface context to supporting components.

Headings automatically adapt their color when rendered on a dark surface:


```tsx
render(<Section innerSpace={{
  block: true
}} surface="dark">
      <H1 size="large" top={false} bottom={false}>
        Heading on dark surface
      </H1>
    </Section>)
```



  
```tsx
<ComponentBox scope={{
HWrap
}} data-visual-test="heading-sizes">
      <HWrap size="xx-large" />
      <HWrap size="x-large" />
      <HWrap size="large" />
      <HWrap size="medium" />
      <HWrap size="basis" />
      <HWrap size="small" />
      <HWrap size="x-small" />
    </ComponentBox>
<ComponentBox scope={{
HWrap
}} data-visual-test="heading-base">
      <H>default (h1 - xx-large)</H>
      <H element="h2">custom level (h2 - xx-large)</H>
      <H size="small">custom size (h1 - small)</H>
      <H element="h2" size="small">
        custom level and size (h2 - small)
      </H>
    </ComponentBox>
```

<!-- eufemia-properties-usage:start -->
Some properties provide flexibility for specific integrations. Follow the component's usage guidance. Customizations beyond the documented patterns need a use case approved by DNB UX. [Read about intended use and customization](/web/styling-and-themes/configuration/component-properties/#intended-use-and-customization).
<!-- eufemia-properties-usage:end -->

## Properties


```json
{
  "props": {
    "family": {
      "doc": "Sets the font family. Display is experimental. [Contact the Eufemia team](/design-system/contact) before use. Use it only for short, expressive headlines. Display has one upright weight.",
      "type": [
        "\"basis\"",
        "\"default\"",
        "\"heading\"",
        "\"monospace\"",
        "\"display\""
      ],
      "status": "optional"
    },
    "size": {
      "doc": "Define the typography [font-size](/web/layout-and-typography/typography/font-size) by a size _type_, e.g. `x-large`. Use `auto` to use the size of the heading level. `H` defaults to `xx-large`, and `H1` to `H6` default to `auto`.",
      "type": [
        "\"auto\"",
        "\"xx-large\"",
        "\"x-large\"",
        "\"large\"",
        "\"medium\"",
        "\"basis\"",
        "\"small\"",
        "\"x-small\""
      ],
      "status": "optional"
    },
    "level": {
      "doc": "Set to `use` to let the automated [Heading](/web/components/heading) levels continue from the level of this element. For example, `<H3 level=\"use\" />` makes the next `Heading` use level 3.",
      "type": "\"use\"",
      "status": "optional"
    },
    "proseMaxWidth": {
      "doc": "Sets the maximum width based on character count. This will limit the text width to approximately the specified number of characters. Use `true` for a default value of 60ch.",
      "type": [
        "number",
        "boolean"
      ],
      "status": "optional"
    },
    "element": {
      "doc": "Defines the HTML element of `H`, like `h2`. `H1` to `H6` always use their own heading element. Defaults to `h1`.",
      "type": "string",
      "status": "optional"
    },
    "ref": {
      "doc": "Send along a custom `React.Ref`.",
      "type": "React.RefObject",
      "status": "optional"
    },
    "children": {
      "doc": "Contents.",
      "type": "React.ReactNode",
      "status": "optional"
    },
    "[Space](/web/layout-and-typography/layout/space/properties)": {
      "doc": "Spacing properties like `top` or `bottom` are supported.",
      "type": [
        "string",
        "object"
      ],
      "status": "optional"
    },
    "skeleton": {
      "doc": "If set to `true`, an overlaying skeleton with animation will be shown.",
      "type": "boolean",
      "status": "optional"
    },
    "skeletonMethod": {
      "doc": "Can be `shape`, `font` or `code`. Defaults to `font`.",
      "type": [
        "\"shape\"",
        "\"font\"",
        "\"code\""
      ],
      "status": "optional"
    }
  },
  "usageGuidance": "Some properties provide flexibility for specific integrations. Follow the component's usage guidance. Customizations beyond the documented patterns need a use case approved by DNB UX. [Read about intended use and customization](/web/styling-and-themes/configuration/component-properties/#intended-use-and-customization)."
}
```


The [Heading](/web/components/heading/properties) component has its own properties for automated heading levels.