DisplayHeading
Hero example
Display heading
When to use
<DisplayHeading> is the marketing-surface display heading. Five sizes carry distinct geometric weight (mega → sub). The size you pick is independent of the HTML heading level — use as to set the right semantic element for the page outline.
For new product code in apps/app, prefer the level-aware atoms <HDisplay> / <H1> / <H2> / <H3> from @matter/components — same recipes, but the level is encoded in the component name, which reads cleaner in dashboard markup.
size) from the document level (as). A size="hero" headline can be as="h2" if the page already has an h1.Anatomy
A single heading element (default <h2>, override via as) with one size class. CSS class hooks per size — each carries a V1 alias for backward compatibility:
| Size | V2 class | V1 alias |
|---|---|---|
mega | .display-mega | (standalone — no V2 alias yet) |
hero | .m-h-display | .display-hero |
section | .m-h1 | .display-section |
card | .m-h2 | .display-card |
sub | .m-h3 | .display-sub |
The aliases share one CSS rule each, so V1 <DisplayHeading> (from @repo/brand/components/display-heading) and V2 <DisplayHeading> (from @matter/components) render pixel-identically during the action 9 consumer migration.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| size | DisplayHeadingSize | "section" | — |
| as | React.ElementType | — | — |
| children | React.ReactNode | — | — |
Also accepts Omit<React.HTMLAttributes<HTMLHeadingElement>, "children">.
size controls the visual recipe; as controls the semantic level. Both are independent and should be set deliberately.
States
DisplayHeading is stateless.
Density
Density-agnostic — display headings ignore the site density toggle. Marketing-tier typography has a fixed visual identity.
Themes
Display heading
Display heading
Display heading
Tokens consumed
Each size reads its corresponding --display-* token family — font-size, line-height, letter-spacing all controlled there.
Accessibility
- Keyboard interactions. None — heading elements are not interactive. Screen-reader users navigate via heading shortcuts.
- ARIA roles and properties. Inherits implicit role from
as(headingfor h1–h6). Level set viaas="h2",as="h3", etc. - Focus order. N/A. Heading anchors (when present) carry
scroll-margin-topso anchored navigation doesn't bury the heading under a sticky header (WIG accessibility rule). - Screen-reader expectations. Announces as "
{text}, heading, level N." - Reduced motion. N/A.
- Forced colors. Renders as
WindowText. Weight and tracking preserved. - WIG rules. Hierarchical headings (h1 → h2 → h3, no skipping) —
aschoice respects the page's heading outline.scroll-margin-topon anchored headings (WIG headings rule).
Do / Don't
size by visual weight ("how big should this read?") and as by document level ("what level in the outline is this?").mega for hero headlines, hero for sub-hero / section openers, section for major sections, card for card titles, sub for sub-headings.<DisplayHeading size="mega"> more than once per page. The mega size is the visual centre; one per page.<HDisplay> / <H1> / <H2> / <H3> from @matter/components inside apps/app. Level-aware atoms read cleaner in dashboard code.@repo/brand/components/display-heading import once the consumer migration has landed. The V2 alias is canonical.Recipes
This component appears in:
- The marketing site's hero blocks.
- Docs corpus recipe — page-title headings.
Code example
import { DisplayHeading } from "@matter/components";
export function PricingHero() {
return (
<DisplayHeading as="h1" size="mega">
Form your company in 90 seconds.
</DisplayHeading>
);
}Source
packages/components/src/DisplayHeadingPillHeader
Glass-pill row used in How-It-Works section headers — left side: lifecycle dot + label; right side: primary CTA + Docs link. Port of the v2 marketing-page section header treatment.
OrgMark
26×26 organisation swatch with initials. Used by the sidebar header trigger and the org-switcher drawer rows. The accent maps to a --role-* token with a sensible hex fallback when the canonical ring isn't wired.