Skip to main content
Digitaltableteur

Design system components

Title

Semantic heading (h1 to h6) with size and line-height variants; the heading level is independent of the visual size.

Status: stable. Group: display. Markdown version: /design-system/components/title.md

When to use

Title renders page and section headings with the semantic level decoupled from the visual scale: pick the h1 to h6 tag with level or as, then choose the size (xxs to xxl) independently, so the document outline stays honest while the layout gets the right optics.

When not to use

  • Do not default Title typography on pattern headings that already define font-display or module classes; use unstyled + existing className.
  • Do not visually size a heading by passing custom inline styles; use the size variants so the typography stays in the system.
  • Do not nest a Title inside a Button. Use the Button's text slot directly.
  • Do not use Title for body copy or form labels; Text and Label own those semantics.

Look-alikes

  • Button: Do not nest a Title inside a Button. Use the Button's text slot directly.
  • Display: Do not use Display for section headings; that is the Title ladder (levels decoupled from sizes).
  • Text: Do not use Text for section headings; headings carry outline semantics Text does not, use Title.

Props

Title props
PropTypeDefaultDescriptionRequired
childrenReact.ReactNode | ReactI18NextChildren | Iterable<ReactI18NextChildren>noneHeading text.Yes
as"h1" | "h2" | "h3" | "h4" | "h5" | "h6"noneOverride the rendered element (h1-h6); wins over level.No
classNamestring | undefined""Additional CSS class names.No
unstyledbooleanfalseWhen true, only sets the heading tag + className (no Title token typography). Use in patterns/pages that already define font/size in CSS or Tailwind.No
size"xl" | "xs" | "s" | "xxs" | "m" | "l" | "xxl"lDisplay size token for the heading.No
level1 | 2 | 3 | 4 | 5 | 6noneSemantic heading level (maps to h1-h6 when as is unset).No
lineHeight"normal" | "tight" | "snug" | "relaxed" | "loose"noneLine height variant.No
flushbooleanfalseDrop the block margins. Use when the parent owns spacing: a row, a cell, a card or a flex/grid gap.No

Variants

  • Available sizes: xxs, xs, s, m, l, xl, xxl (default l).
  • Allowed as values: h1, h2, h3, h4, h5, h6.
  • Allowed level values: 1, 2, 3, 4, 5, 6.
  • Allowed lineHeight values: normal, tight, snug, relaxed, loose.

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Title rules
LevelRuleHow it is checked
MUSTARIA: Use correct heading level via as or level prop.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTThe accessibility tree (role, name, state) matches the committed snapshot for every required story.Automated by npm run test:stories:matrix:ci. WCAG 1.3.1, 4.1.2.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Manual review, last on 2026-11-04.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-11-04.
SHOULDDecide the semantic level from the document outline first, then pick the visual size that fits the layout.Not stated in the contract.
SHOULDAlways pass level or as when the page already has an h1; the default tag is h1.Not stated in the contract.
SHOULDUse size m or s for section headers in product chrome. Title always renders h1 to h6; display text with no place in the outline belongs in Text.Not stated in the contract.
SHOULDReach for size xl or xxl on hero headlines; the visual size scales the optics independently of the semantic level.Not stated in the contract.
SHOULD NOTDo not let the visual size choose the heading level; skipped levels break rotor navigation.Not stated in the contract.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { Title } from "@digitaltableteur/react";
  • Entry point: @digitaltableteur/react/typography exports it too.
  • Styles: import @digitaltableteur/react/style.css once at the app boundary.
  • Also available as the custom element <dt-title>; see the custom elements manifest.

Links