Skip to main content

Heading

The Heading component is a semantic heading component built on top of Text, designed specifically for headings with sensible defaults for each heading level.

Import​

import { Heading } from "@tosui/react";

Basic Usage​

<Heading>Default h1 heading</Heading>

Key Features​

  • Default element: <h1>
  • Semantic levels: Use level prop to control heading hierarchy (h1-h6)
  • Smart sizing: Each level has appropriate default font size
  • Bold by default: Headings use bold weight unless overridden
  • Polymorphic: Can render as any element via as prop
  • Inherits from Text: Access to all Text and Box capabilities

Heading Levels​

The level prop controls both the HTML element and default font size:

<Heading level={1}>Heading 1 (30px, 3xl)</Heading>
<Heading level={2}>Heading 2 (24px, 2xl)</Heading>
<Heading level={3}>Heading 3 (20px, xl)</Heading>
<Heading level={4}>Heading 4 (18px, lg)</Heading>
<Heading level={5}>Heading 5 (16px, md)</Heading>
<Heading level={6}>Heading 6 (14px, sm)</Heading>

Default Size Mapping​

LevelElementDefault SizePixel Size
1<h1>3xl30px
2<h2>2xl24px
3<h3>xl20px
4<h4>lg18px
5<h5>md16px
6<h6>sm14px

Overriding Size​

You can override the default size for any heading level:

<Heading level={2} size="4xl">
  Larger than normal h2
</Heading>

<Heading level={1} size="2xl">
  Smaller than normal h1
</Heading>

Weight​

Headings default to bold weight, but can be customized:

<Heading weight="bold">Bold heading (default)</Heading>
<Heading weight="semibold">Semibold heading</Heading>
<Heading weight="medium">Medium heading</Heading>
<Heading weight="normal">Normal weight heading</Heading>

Available weights: normal | medium | semibold | bold

Color​

Use semantic color tokens:

<Heading color="foreground">Default foreground</Heading>
<Heading color="primary">Primary brand color</Heading>
<Heading color="accent">Accent color</Heading>
<Heading color="foreground-muted">Muted heading</Heading>

Available colors: foreground | foreground-muted | foreground-subtle | primary | primary-emphasis | accent | accent-emphasis | success | warning | error

Polymorphic Rendering​

Separate semantic meaning from visual styling:

{/* Visually h3, semantically h1 */}
<Heading level={1} size="xl">
  Page Title
</Heading>

{/* Render as div but styled as heading */}
<Heading as="div" level={2}>
  Non-semantic heading
</Heading>

Common Patterns​

Page Title​

<Heading level={1} size="4xl" weight="bold">
  Dashboard
</Heading>

Section Heading​

<Heading level={2} size="2xl" weight="semibold">
  Recent Activity
</Heading>

Subsection Heading​

<Heading level={3} size="xl" color="foreground-muted">
  User Details
</Heading>

Card Title​

<Heading level={4} size="lg" weight="semibold">
  Card Title
</Heading>

Small Heading​

<Heading level={6} size="sm" weight="medium" color="foreground-muted">
  Metadata Section
</Heading>

Combining with Box Props​

Since Heading is built on Text (which is built on Box), you can use any Box prop:

<Heading
  level={2}
  mb={4}
  pb={3}
  borderBottom="thin"
  borderColor="border"
>
  Section with Border
</Heading>

Layout Example​

<Box display="flex" flexDirection="column" gap={6}>
  <Box>
    <Heading level={1} size="4xl" mb={2}>
      Main Page Title
    </Heading>
    <Text size="lg" color="foreground-muted">
      Subtitle or description
    </Text>
  </Box>

  <Box>
    <Heading level={2} size="2xl" mb={3}>
      Section Heading
    </Heading>
    <Text>Section content goes here...</Text>
  </Box>

  <Box>
    <Heading level={3} size="xl" mb={2}>
      Subsection
    </Heading>
    <Text>Subsection content...</Text>
  </Box>
</Box>

Accessibility​

The level prop ensures proper heading hierarchy for screen readers:

{/* ✅ Good: Proper hierarchy */}
<Heading level={1}>Page Title</Heading>
<Heading level={2}>Section</Heading>
<Heading level={3}>Subsection</Heading>

{/* ❌ Avoid: Skipping levels */}
<Heading level={1}>Page Title</Heading>
<Heading level={3}>Section</Heading> {/* Skipped h2 */}

If you need different visual sizing without breaking hierarchy:

{/* ✅ Correct semantic hierarchy with custom sizing */}
<Heading level={1} size="3xl">Main Title</Heading>
<Heading level={2} size="4xl">Visually Larger Section</Heading>
<Heading level={3} size="xl">Subsection</Heading>

Props Reference​

Heading-Specific Props​

  • level: Heading level (1-6), controls both HTML element and default size
    • Default: 1
  • size: Override default font size (xs | sm | md | lg | xl | 2xl | 3xl | 4xl | 5xl)
  • weight: Font weight (normal | medium | semibold | bold)
    • Default: bold
  • color: Semantic color token

Inherited from Text​

Heading inherits all props from Text, which includes:

  • Text utilities (truncate, italic, align)
  • All Box props (spacing, layout, borders, etc.)

See the Text component documentation and Box component documentation for the full list.

TypeScript​

Heading is fully typed and provides autocomplete for all props. When using the as prop, TypeScript will correctly infer the allowed HTML attributes for that element type.