Heading

When to use

• A page’s title, once, as level 1
• The title of each section, a level below the section it sits in

Choosing between showing text:

Component	Use it for	Renders	For example
Heading	The title of a page or a section, at a rank in the outline	<h1>–<h6>	A page title, a card title
Paragraph	A block of running text	<p>	Body copy, a description
Text	A run of text inside other text, styled from the tokens	<span>	A date, a count, a name
Kbd	A key or a shortcut	<kbd>	Ctrl + K
Link	Text that goes somewhere	<a>	Read more

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

Starter plan

The level follows the outline; size sets the look.

import { Heading, Paragraph, Stack } from '@arun-dev/ui';

export default function HeadingBasics() {
  return (
    <Stack gap="md">
      {/* Each level at its own size: the default. */}
      <Stack gap="2xs">
        {([1, 2, 3, 4, 5, 6] as const).map((level) => (
          <Heading key={level} level={level}>
            Heading level {level}
          </Heading>
        ))}
      </Stack>

      {/* A card's title is an h3 in this page's outline, but should not look like a section. */}
      <Stack gap="3xs">
        <Heading level={3} size="lg">
          Starter plan
        </Heading>
        <Paragraph color="secondary">The level follows the outline; size sets the look.</Paragraph>
      </Stack>
    </Stack>
  );
}

level is the heading’s rank in the outline, and picks the element: level={3} is an <h3>. Screen reader users move through a page by its headings, so choose the level by structure — the section it heads — and never skip one to get a smaller look.

size is the look, a step on the type scale. Left out, each level has its own size, from 4xl for level 1 down to base for level 6.

Props

Heading props

Prop	Type	Default	Description
level	1 | 2 | 3 | 4 | 5 | 6	2	Its rank in the outline, and so the element: <h1> to <h6>. Choose it by structure.
size	'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl'	'4xl' to 'base', by level	How big it looks, a step on the type scale: the --text-* token of the same name.
className	string	—	Concatenated with the component's own classes, never replacing them.
render	ReactElement	—	Element or component to render instead of the default. Props, className, event handlers and ref are merged onto it.
ref	Ref<HTMLElement>	—	Ref to the rendered element. Merged with any ref on the render element.
…rest	HTMLAttributes	—	Anything else is spread onto the rendered element, so id, aria-*, data-* and event handlers all reach the DOM.

Notes

• A wrapping heading’s lines are balanced, so no word is left alone on the last line.
• Restyle every heading with --heading-font-family, --heading-font-weight, --heading-letter-spacing and --heading-color.
• Heading text that only looks like a heading, such as a label above a value, isn’t one. Use Text.