Heading

A semantic, fluid-sized heading — pick the tag with `as`, the visual size with `size`.

Last updated

Ship faster with Apogee

Same order, a smaller visual weight

Show code
<Heading as="h1">Ship faster with Apogee</Heading>
<Heading as="h2" size="h3">Same order, a smaller visual weight</Heading>

Add

npx @ava-ui/apogee add heading

No Apogee dependencies.

Usage

---
import Heading from '@/components/apogee/Heading/Heading.astro'
---
<Heading as="h1">Page title</Heading>

API

@composable — exposed to Content Editors in AVA. Any other native heading/text attribute (e.g. id, aria-level) passes through.

Prop Type Default Description
as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'div' 'h2' Semantic tag rendered.
size 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' mirrors as (falls back to h2 when as is p/div) Visual size, independent of the semantic tag.
weight 'regular' | 'medium' | 'semibold' | 'bold' 'semibold' Font weight.
color 'neutral' | 'neutral-faded' | 'primary' | 'critical' | 'positive' | 'warning' — Text hue. Unset inherits the surrounding colour, so a heading inside a solid fill keeps the on-colour.
maxLines 1 | 2 | 3 | 4 | 5 | 6 — Clamp with an ellipsis (same scale as Text).
align 'start' | 'center' | 'end' — Text alignment.
class string — Extra classes, merged last.

Sizes

Every size. Rendered here on as="div" so the outline stays clean — in real pages, prefer picking the right as first.

Display
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Show code
<Heading as="div" size="display">Display</Heading>
<Heading as="div" size="h1">Heading 1</Heading>
<Heading as="div" size="h2">Heading 2</Heading>
<Heading as="div" size="h3">Heading 3</Heading>
<Heading as="div" size="h4">Heading 4</Heading>
<Heading as="div" size="h5">Heading 5</Heading>
<Heading as="div" size="h6">Heading 6</Heading>

Weight

Regular

Medium

Bold

A very long heading that is clamped to one line with an ellipsis

Show code
<Heading as="h3" weight="regular">Regular</Heading>
<Heading as="h3" weight="medium">Medium</Heading>
<Heading as="h3" weight="bold">Bold</Heading>
<Heading as="h3" maxLines={1}>A very long heading that is clamped to one line with an ellipsis</Heading>

Colours

Every color. Without one, a heading inherits the surrounding text colour.

Neutral
Neutral faded
Primary
Critical
Positive
Warning
Show code
<Heading as="div" size="h4" color="neutral">Neutral</Heading>
<Heading as="div" size="h4" color="neutral-faded">Neutral faded</Heading>
<Heading as="div" size="h4" color="primary">Primary</Heading>
<Heading as="div" size="h4" color="critical">Critical</Heading>
<Heading as="div" size="h4" color="positive">Positive</Heading>
<Heading as="div" size="h4" color="warning">Warning</Heading>

Alignment

Start
Center
End
Show code
<Heading as="div" size="h4" align="start">Start</Heading>
<Heading as="div" size="h4" align="center">Center</Heading>
<Heading as="div" size="h4" align="end">End</Heading>

States

Static: no interactive states. color and maxLines are the only visual variations.

Examples

Decouple visual weight from document order — a card title that’s semantically an h3 but should look smaller than the page’s other h3s:

<Heading as="h3" size="h5">Card title</Heading>

Accessibility

  • Renders the real tag passed to as — screen readers get an accurate heading outline.
  • Keep heading order sequential (h1 → h2 → h3, no skipping) even when size makes the visual weight diverge from as.
  • as="p" / as="div" removes the element from the heading outline entirely — use it when text should merely look like a heading without appearing in the page’s structure.
  • Native semantics, no extra ARIA needed.

Tokens

Token Used for
--text-display / --text-h1 … --text-h6 (each paired with its own line-height) Fluid font size + line height per size
--foreground-neutral Text colour

Do / Don’t

  • Do choose as for correct document outline first, then adjust size for visual weight.
  • Do keep exactly one h1 per page.
  • Don’t skip heading levels for visual reasons — use size instead of jumping from h2 to h5.
  • Don’t use Heading to style body copy — reach for as="p"/as="div" only when the text is heading-like but shouldn’t join the outline.

Content

  • Short, front-loaded phrases — lead with the key word, sentence case, no ending period.
  • Avoid vague headings (“More information”) — name the actual content.

Related

TextBody copy with a size scale and semantic colours. Renders p, span, or div.
EyebrowA small label above a heading, for section tags and category kickers.
ProseTypography styling for a block of rich, CMS, or markdown HTML you don't control element by element.