> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/system-ui/theme-ui/llms.txt
> Use this file to discover all available pages before exploring further.

# Heading

> Primitive heading component with semantic heading levels

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

## Import

```jsx theme={null}
import { Heading } from 'theme-ui'
```

## Usage

```jsx theme={null}
<Heading>Default Heading</Heading>
```

## Props

<ParamField path="as" type="'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'" default="'h2'">
  Semantic heading level. Defaults to `h2`.

  ```jsx theme={null}
  <Heading as="h1">Page Title</Heading>
  <Heading as="h2">Section Title</Heading>
  <Heading as="h3">Subsection Title</Heading>
  ```
</ParamField>

<ParamField path="variant" type="string" default="'heading'">
  Text variant from `theme.text`. The default `heading` variant uses `theme.text.heading`.

  ```jsx theme={null}
  <Heading variant="heading">Default heading style</Heading>
  <Heading variant="display">Display style</Heading>
  <Heading variant="caps">ALL CAPS HEADING</Heading>
  ```
</ParamField>

<ParamField path="sx" type="ThemeUIStyleObject">
  Theme-aware styles for custom heading appearance.

  ```jsx theme={null}
  <Heading
    sx={{
      fontSize: 6,
      color: 'primary',
      mb: 3,
    }}
  >
    Custom Heading
  </Heading>
  ```
</ParamField>

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

```js theme={null}
{
  fontFamily: 'heading',
  fontWeight: 'heading',
  lineHeight: 'heading',
}
```

These map to `theme.fonts.heading`, `theme.fontWeights.heading`, and `theme.lineHeights.heading`.

## Examples

### Semantic Headings

```jsx theme={null}
<Heading as="h1">Main Page Title</Heading>
<Heading as="h2">Section Heading</Heading>
<Heading as="h3">Subsection</Heading>
```

### Responsive Heading

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

### Colored Heading

```jsx theme={null}
<Heading color="primary">
  Primary Colored Heading
</Heading>
```

### Custom Heading

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

### Heading with Underline

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

### Centered Heading

```jsx theme={null}
<Heading sx={{ textAlign: 'center' }}>
  Centered Heading
</Heading>
```

### Heading with Gradient

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