Skip to main content
The Heading component is a primitive component for rendering semantic headings (h1-h6) with theme-aware typography.

​
Import

import { Heading } from 'theme-ui'

​
Usage

<Heading>Default Heading</Heading>

​
Props

​
as
'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
default:"'h2'"
Semantic heading level. Defaults to h2.
<Heading as="h1">Page Title</Heading>
<Heading as="h2">Section Title</Heading>
<Heading as="h3">Subsection Title</Heading>
​
variant
string
default:"'heading'"
Text variant from theme.text. The default heading variant uses theme.text.heading.
<Heading variant="heading">Default heading style</Heading>
<Heading variant="display">Display style</Heading>
<Heading variant="caps">ALL CAPS HEADING</Heading>
​
sx
ThemeUIStyleObject
Theme-aware styles for custom heading appearance.
<Heading
  sx={{
    fontSize: 6,
    color: 'primary',
    mb: 3,
  }}
>
  Custom Heading
</Heading>

​
Inherited Props

Heading extends Box and accepts:
  • All standard HTML heading attributes
  • Box spacing props (m, p, mx, my, px, py, etc.)
  • Box color props (color, bg, opacity)

​
Default Styles

The Heading component includes these base styles: 
{
  fontFamily: 'heading',
  fontWeight: 'heading',
  lineHeight: 'heading',
}
These map to theme.fonts.heading, theme.fontWeights.heading, and theme.lineHeights.heading.

​
Examples

​
Semantic Headings

<Heading as="h1">Main Page Title</Heading>
<Heading as="h2">Section Heading</Heading>
<Heading as="h3">Subsection</Heading>

​
Responsive Heading

<Heading
  as="h1"
  sx={{
    fontSize: [4, 5, 6],
  }}
>
  Responsive Title
</Heading>

​
Colored Heading

<Heading color="primary">
  Primary Colored Heading
</Heading>

​
Custom Heading

<Heading
  as="h2"
  sx={{
    fontFamily: 'body',
    fontWeight: 'normal',
    fontSize: 5,
    color: 'secondary',
    mb: 4,
  }}
>
  Custom Styled Heading
</Heading>

​
Heading with Underline

<Heading
  sx={{
    pb: 2,
    borderBottom: '2px solid',
    borderColor: 'primary',
  }}
>
  Underlined Heading
</Heading>

​
Centered Heading

<Heading sx={{ textAlign: 'center' }}>
  Centered Heading
</Heading>

​
Heading with Gradient

<Heading
  sx={{
    background: 'linear-gradient(90deg, #667eea 0%, #764ba2 100%)',
    WebkitBackgroundClip: 'text',
    WebkitTextFillColor: 'transparent',
  }}
>
  Gradient Heading
</Heading>

Build docs developers (and LLMs) love

Get started for freeTalk to us