Heading — DS-GN Docs

The <dsgn-heading> component renders headings with responsive font sizing, so type scales fluidly across breakpoints.

Usage

<dsgn-heading heading-size="h2">Section title</dsgn-heading>

Import the component module in your application entrypoint:

import '@ds-gn/ui/heading';

Playground

Props

Prop	Type	Default	Description
heading-size	`'h1'` \| `'h2'` \| `'h3'` \| `'h4'` \| `'h5'` \| `'h6'` \| `'hero'`	`'h1'`	Heading level or hero style.
heading-weight	`'normal'` \| `'semibold'` \| `'bold'` \| `'extrabold'`	`'normal'`	Font weight for the heading text.
surface	`'light'` \| `'dark'`	`'light'`	Surface tone for heading color styling.
words	`string[]`	`undefined`	Optional word list to cycle through in place of static text.
word-interval	`number`	`undefined`	Milliseconds between word changes when `words` is set.
word-cycles	`number`	`1`	How many times to cycle the word list.

heading-size, heading-weight, word-interval, and word-cycles are the attribute names; the matching JavaScript properties are headingSize, headingWeight, wordInterval, and wordCycles.

Slots

Slot	Description
(default)	Heading text content.

heading-size picks both the type scale and the rendered element: h1 through h6 render the matching tag, and hero renders an <h1> at the largest scale.

Word cycling

Set words to animate a swapping word after the slotted text. The list is cycled every word-interval milliseconds (default 1000) and stops after word-cycles passes.

<dsgn-heading
  heading-size="hero"
  words='["faster", "safer", "together"]'
  word-interval="1400"
  word-cycles="3"
>
  Ship
</dsgn-heading>

const heading = document.querySelector('dsgn-heading');
heading.words = ['faster', 'safer', 'together'];
heading.wordInterval = 1400;

The cycle needs at least two words. It pauses while the heading is off-screen and does not run at all when the user prefers reduced motion — the first word stays in place.

Examples

Sizes

<dsgn-heading heading-size="hero">Hero</dsgn-heading>
<dsgn-heading heading-size="h1">Heading 1</dsgn-heading>
<dsgn-heading heading-size="h2">Heading 2</dsgn-heading>
<dsgn-heading heading-size="h3">Heading 3</dsgn-heading>
<dsgn-heading heading-size="h4">Heading 4</dsgn-heading>
<dsgn-heading heading-size="h5">Heading 5</dsgn-heading>
<dsgn-heading heading-size="h6">Heading 6</dsgn-heading>

Weight

<dsgn-heading heading-size="h2" heading-weight="bold"
  >Bold section title</dsgn-heading
>

Dark surface

<dsgn-heading heading-size="h1" surface="dark"
  >Dark background title</dsgn-heading
>

Accessibility

Use heading-size to match the document outline and avoid skipping levels. hero renders an <h1>, so use it once per page.
Ensure heading text is descriptive of the section content.
Word cycling honors prefers-reduced-motion: the heading renders the first word statically instead of animating. Keep the slotted text meaningful on its own so the heading reads correctly with any word showing.

Usage patterns

Use heading-size="hero" for page-level titles only.
Apply surface="dark" when the heading is rendered on dark backgrounds to maintain contrast.