Primitive / Atomstable

Heading

Semantic heading primitive with independent style scaling.

@glinui/uiComponent: heading

Installation$

Install from the package for shared ownership or from the registry for copy-paste control.

Package Manager$

pnpm add @glinui/ui @glinui/tokens

Registry$

pnpm dlx @glinui/cli@latest add heading

Usage$

Heading renders the correct semantic <h1>–<h6> element determined by the level prop, while the size prop controls the visual font scale independently. This decouples document structure from visual hierarchy — a section subheading can use level={3} for correct outline order while appearing large with size="lg".

Basic$

Heading Level 1

Heading Level 2

Heading Level 3

TSX

1import { Heading } from "@glinui/ui"
2
3export function HeadingBasicDemo() {
4return (
5  <div className="space-y-2">
6    <Heading level={1}>Heading Level 1</Heading>
7    <Heading level={2}>Heading Level 2</Heading>
8    <Heading level={3}>Heading Level 3</Heading>
9  </div>
10)
11}

Examples$

Variants$

The variant prop applies a surface treatment — useful when a heading needs to sit on a glass card or a transparent overlay.

Default Heading

Glass Heading

Outline Heading

Ghost Heading

TSX

1import { Heading } from "@glinui/ui"
2
3export function HeadingVariantDemo() {
4return (
5  <div className="space-y-2">
6    <Heading variant="default">Default Heading</Heading>
7    <Heading variant="glass">Glass Heading</Heading>
8    <Heading variant="outline">Outline Heading</Heading>
9    <Heading variant="ghost">Ghost Heading</Heading>
10  </div>
11)
12}

Sizes$

Small heading

Medium heading

Large heading

TSX

1import { Heading } from "@glinui/ui"
2
3export function HeadingSizeDemo() {
4return (
5  <div className="space-y-2">
6    <Heading size="sm">Small heading</Heading>
7    <Heading size="md">Medium heading</Heading>
8    <Heading size="lg">Large heading</Heading>
9  </div>
10)
11}

Independent Level and Size$

The key feature of Heading is that semantic level and visual size are fully independent. An h3 can visually appear as large as a page title, and an h1 can be styled small for compact interfaces — all without breaking document outline order.

Large h3 — section title styled like a hero heading

Small h1 — compact page title

Default h4 subsection

TSX

1import { Heading } from "@glinui/ui"
2
3export function HeadingIndependentDemo() {
4return (
5  <div className="space-y-4">
6    {/* Visually large, semantically an h3 */}
7    <Heading level={3} size="lg">
8      Large h3 — section title styled like a hero heading
9    </Heading>
10
11    {/* Visually small, semantically an h1 — e.g., page header in a compact layout */}
12    <Heading level={1} size="sm">
13      Small h1 — compact page title
14    </Heading>
15
16    {/* h4 at default md size — standard subsection */}
17    <Heading level={4} size="md">
18      Default h4 subsection
19    </Heading>
20  </div>
21)
22}

Full Level Range$

h1 — Page title

h2 — Section

h3 — Subsection

h4 — Group

h5 — Detail

h6 — Caption-level

TSX

1import { Heading } from "@glinui/ui"
2
3export function HeadingLevelsDemo() {
4return (
5  <div className="space-y-1">
6    <Heading level={1}>h1 — Page title</Heading>
7    <Heading level={2}>h2 — Section</Heading>
8    <Heading level={3}>h3 — Subsection</Heading>
9    <Heading level={4}>h4 — Group</Heading>
10    <Heading level={5}>h5 — Detail</Heading>
11    <Heading level={6}>h6 — Caption-level</Heading>
12  </div>
13)
14}

Accessibility$

Always use headings in a logical, non-skipping order (h1 → h2 → h3) to maintain a coherent document outline for screen readers.
The level prop controls the rendered HTML tag — never override this with CSS display tricks that break semantics.
Decoupling level from size lets you meet visual design requirements without compromising heading hierarchy.
Avoid using multiple level={1} headings on a single page; pages should have exactly one <h1>.

Reduced Motion$

Heading is a static text primitive with no animation. No reduced-motion considerations apply.

API Reference$

Prop	Type	Required	Default	Description
`level`	`HeadingLevel`	No	`2`	Auto-generated from TypeScript source.
`size`	`"sm" \| "md" \| "lg"`	No	`"md"`	Variant option from headingVariants.
`variant`	`"default" \| "glass" \| "outline" \| "ghost"`	No	`"default"`	Variant option from headingVariants.

Source$

TSX

1import { Heading } from "@glinui/ui"

packages/ui/src/components/heading.tsx

Generated API Snapshot

Beta

Auto-extracted from TypeScript source in packages/ui/src/components/heading.tsx. This section is in beta and may lag behind hand-curated docs. Regenerate with pnpm --filter @glinui/docs api:generate.

Generated: 2026-02-19T17:59:28.468Z · Full index: /docs/api-metadata

Primary Props Type

HeadingProps

`HeadingProps`

Prop	Type	Required	Default	Description
`level`	`HeadingLevel`	No	`2`	-
`size`	`"sm" \| "md" \| "lg"`	No	`"md"`	Variant option from headingVariants.
`variant`	`"default" \| "glass" \| "outline" \| "ghost"`	No	`"default"`	Variant option from headingVariants.