Heading

Heading renders an h1 through h6 and assigns a default size for that level. It renders an h1 by default.

Open in Storybook

Import

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

Basic usage

Preview

Code

<Heading>Default h1 heading</Heading>

Heading levels

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

Preview

Heading 1 (30px, 3xl)

Heading 2 (24px, 2xl)

Heading 3 (20px, xl)

Heading 4 (18px, lg)

Heading 5 (16px, md)

Heading 6 (14px, sm)

Code

<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

Level	Element	Default Size	Pixel Size
1	<h1>	3xl	30px
2	<h2>	2xl	24px
3	<h3>	xl	20px
4	<h4>	lg	18px
5	<h5>	md	16px
6	<h6>	sm	14px

Override the size

Pass size to change the visual size without changing the heading level.

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

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

Weight

Headings use bold by default. Pass weight to override the default.

Preview

Bold heading (default)

Semibold heading

Medium heading

Normal weight heading

Code

<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 are normal, medium, semibold, and bold.

Color

Use a text color token:

Preview

Default foreground

Primary brand color

Accent color

Muted heading

Code

<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>

Heading accepts the same foreground, brand, and feedback text colors as Text.

Polymorphic rendering

The as prop overrides the element selected by level. The level still selects the default size.

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

{/* Render a div with the default h2 size. */}
<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>

Style the surrounding box

Heading accepts the Box props that Text inherits. It replaces fontSize, fontWeight, textAlign, and color with size, weight, align, and its own color 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

Keep heading levels in document order. Change the visual size with size instead of skipping a level.

{/* Keep levels in order. */}
<Heading level={1}>Page Title</Heading>
<Heading level={2}>Section</Heading>
<Heading level={3}>Subsection</Heading>

{/* Do not skip levels. */}
<Heading level={1}>Page Title</Heading>
<Heading level={3}>Section</Heading> {/* Skipped h2 */}

If you need different visual sizing without breaking hierarchy:

{/* Keep semantic levels while changing visual sizes. */}
<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 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

Props inherited from Text

Heading inherits the following groups from Text:

• Text utilities (truncate, italic, align)
• The Box props that Text does not replace, including spacing, layout, borders, and state props

See the Text reference and the Box reference for the complete lists.

TypeScript

import { Heading, type HeadingProps } from "@tosui/react";

HeadingProps<T> includes the native attributes for the element type T.