Heading

When to useLink to "When to use"

• A page title: level={1}, once per page. Add size="display" for a hero title.
• A section or panel title: level from the page structure (a section inside a level 2 section is level 3), then size if the default looks too large or too small there.
• A compact heading in dense UI: a small size with tone="muted", still at the right level.

Use something else when:

• the text is not a heading (body copy, captions, labels): Text
• it is rendered Markdown or other plain HTML: Prose, which styles the headings inside it
• it is the title of an empty view with an icon and a next step: EmptyState
• it labels a form control: Field

UsageLink to "Usage"

import { Heading } from "@arshad-shah/cynosure";

<Heading level={1}>Projects</Heading>
<Heading>Recent exports</Heading>
<Heading level={2} size="sm" tone="muted">Filters</Heading>
<Heading level={1} size="display" align="center">Capture anything</Heading>
<Heading level={3} truncate>{file.name}</Heading>

Level and sizeLink to "Level and size"

Without size, each level takes its own step of the type scale: level 1 is 2xl, 2 is xl, 3 is lg, 4 is md, 5 is sm and 6 is xs. Setting size changes the look only. Every heading below is an h3. display grows with the viewport and stays between 1.25 and 2 times 2xl.

Tone, weight and alignmentLink to "Tone, weight and alignment"

tone is neutral (the ink colour), muted, accent or inherit (the colour of whatever the heading sits in). weight is bold or medium. align is start, center or end. Left unset, the heading follows its parent's alignment.

TruncationLink to "Truncation"

truncate keeps the heading on one line and ends it with an ellipsis. A number cuts it after that many lines. Text that fits is left alone.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

Heading is not interactive: it has no keyboard or pointer behaviour.

• Outline: it renders a real h1 to h6, so it appears in the page outline and in screen reader heading lists at level. Choose the level from the page structure and the size from the design.
• Naming a region: pass id and point aria-labelledby at it.
• Truncated text: the full text stays the heading's accessible name.
• Wrapping: lines are balanced (text-wrap: balance), and long words break instead of overflowing.
• No margins: space headings with Stack or the layout around them.
• Right to left: start and end swap sides, and a truncated heading keeps the start of its text.
• Ref: the forwarded ref is the heading element.

TouchLink to "Touch"

Nothing in Heading is pressable, so it has no hit area.

ThemingLink to "Theming"

Tokens: --cy-heading-size-{xs,sm,md,lg,xl,2xl,display}, --cy-heading-font-family, --cy-heading-font-weight and --cy-heading-line-height.

createTheme({ components: { heading: { sizeXl: "1.5rem", "size-2xl": "2rem", lineHeight: "1.15" } } });

className and style are for layout only (margin, placement, width). Change the look through tokens so every product stays consistent.

RelatedLink to "Related"

Prose · Stack · EmptyState