heading

Styled semantic heading. Renders the correct HTML tag (h1–h6) with consistent typography tokens. Use this instead of raw heading tags so you get the right visual style without remembering utility classes.

All levels

Each level has a default visual size. The semantic tag and visual size are independent — see size override below.

Heading level 1

Heading level 2

Heading level 3

Heading level 4

Heading level 5

Heading level 6

heading({ level: 1, text: 'Page title' })
heading({ level: 2, text: 'Section title' })
heading({ level: 3, text: 'Subsection' })
heading({ level: 4, text: 'Card heading' })
heading({ level: 5, text: 'Label' })
heading({ level: 6, text: 'Caption' })

Size override

The size prop lets you use a different visual scale than the default for that level. Useful when you need the correct semantic structure for SEO or accessibility but want a different visual weight.

Semantic h2, looks like h4

Semantic h3, extra large

// h2 for structure, but visually smaller
heading({ level: 2, text: 'Related articles', size: 'xl' })

// h3 that needs to be visually prominent
heading({ level: 3, text: 'Featured', size: '4xl' })

Color

Default colour

Muted — for secondary labels

Accent — for highlights

heading({ level: 3, text: 'Default colour' })
heading({ level: 3, text: 'Muted — for secondary labels', color: 'muted' })
heading({ level: 3, text: 'Accent — for highlights', color: 'accent' })

Spacing

heading() adds no margin. Use u-mt-* and u-mb-* utility classes to control spacing in context.

Account settings

Manage your profile and preferences.

card({ content: `
  ${heading({ level: 2, text: 'Account settings', class: 'u-mb-2' })}
  <p class="u-text-muted u-text-sm">Manage your profile and preferences.</p>
`})

Preventing orphans

When a heading wraps across lines, the last line can be left with a single short word — an orphan. The balance prop adds text-wrap: balance, which distributes text evenly across all lines so no word is stranded.

The quick brown fox jumps over the lazy dog tonight

↑ without balance — ↓ with balance: true

The quick brown fox jumps over the lazy dog tonight

// Without — last line may have a single word
heading({ level: 2, text: 'The quick brown fox jumps over the lazy dog tonight' })

// With — text distributed evenly across lines
heading({ level: 2, text: 'The quick brown fox jumps over the lazy dog tonight', balance: true })

Prop	Type	Default
`level`	number (1–6)	2	Controls both the HTML tag and the default visual size
`text`	string	—	Heading text — escaped automatically
`size`	`xs \| sm \| base \| lg \| xl \| 2xl \| 3xl \| 4xl`	—	Override the visual font size independently of the semantic level. Defaults: h1=4xl, h2=3xl, h3=2xl, h4=xl, h5=base, h6=sm
`color`	`default \| muted \| accent`	`default`	Text colour token
`balance`	boolean	`false`	Adds `text-wrap: balance` — prevents orphaned words on the last line when the heading wraps
`class`	string	—	Extra classes — use for spacing utilities such as `u-mb-4`