Heading
A responsive heading renderer that maps a visual size scale onto the correct semantic HTML heading element. Supports fluid typography, colour, alignment, weight, and ellipsis truncation.
When to use
Do
- ✓Use diwa-heading for all page titles, section headings, card titles, and UI labels that require heading semantics.
- ✓Choose the size that reflects the actual content hierarchy — display and h1 for top-level page titles, h2–h4 for sections and subsections.
- ✓Use the tag prop when the visual size must differ from the semantic heading level, such as a visually small h2 inside a complex card layout.
- ✓Use color="secondary" to de-emphasise supporting or contextual headings.
- ✓Pair a display or h1 heading with a secondary h3 subheading for hero and editorial sections.
Don't
- ✕Don't use diwa-heading for body text, captions, or labels — use diwa-text instead.
- ✕Don't skip heading levels for visual reasons alone. Jumping from h2 to h5 breaks document outline and screen reader navigation.
- ✕Don't use multiple h1 elements on a single page — each page should have exactly one top-level heading.
- ✕Don't use display size for anything other than hero or marketing headlines — it is too large for standard UI headings.
- ✕Don't forget to constrain the host width before enabling ellipsis — without a max-width the text will never truncate.
Size guidance
display (24→36px fluid) — Hero titles, marketing headlines, empty-state illustrations. Use sparingly — once per view at most.
h1 (20→28px fluid) — Top-level page heading. One per page. Sets the primary document context.
h2 (18→24px fluid) — Major section headings. Divides a page into named regions.
h3 (16→20px fluid) — Subsection headings. Organises content within an h2 region.
h4 (14→17px fluid) — Card titles, panel headers, group labels. Inline headings within a content area.
h5 (13→15px fluid) — Small group labels, metadata headings, sidebar sections.
h6 (11→13px fluid) — Fine-grained labels on dense interfaces. Use sparingly — prefer diwa-text for smaller label text.
Tag override guidance
By default, size determines the rendered HTML tag — a size="h3" heading renders as <h3>. This keeps visual hierarchy and document outline in sync for the common case.
Use tag to break the coupling when necessary. A common pattern is a visually prominent heading whose semantic level is constrained by the surrounding document outline — e.g. a card title that must be <h4> for outline continuity but visually renders at h2 size.
When a direct child of the heading slot is itself an h1–h6 element, the component automatically renders as <div> to prevent invalid nested heading markup.
Fluid typography
All heading sizes use fluid font-size tokens (--diwa-font-size-fluid-*) that scale continuously between a minimum and maximum size using CSS clamp(). This means headings adapt to the viewport width without breakpoint overrides.
Use the CSS custom property override API (--diwa-heading-font-size) only when a component-level size override is genuinely needed — prefer choosing the right size value first.