Heading

Semantic heading element.

The quick brown fox jumps over the lazy dog

<.heading>The quick brown fox jumps over the lazy dog</.heading>

API Reference

This component is based on the h1 element and supports common margin props.

Prop	Type	Default	Description
`align`	`string`	`—`	Text alignment: one of left, center, right.
`as`	`string`	`"h1"`	The element to render. h1-h6.
`class`	`string`	`nil`	Additional CSS classes.
`color`	`string`	`—`	Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky.
`high_contrast`	`boolean`	`—`	Whether to increase color contrast with the background.
`m`	`any`	`—`	Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
`mb`	`any`	`—`	Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
`ml`	`any`	`—`	Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
`mr`	`any`	`—`	Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
`mt`	`any`	`—`	Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
`mx`	`any`	`—`	Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
`my`	`any`	`—`	Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`
`size`	`string`	`—`	Heading size (1-9). Responsive supported.
`style`	`string`	`nil`	Additional inline styles.
`trim`	`string`	`—`	Trim leading space: one of normal, start, end, both.
`truncate`	`boolean`	`—`	Whether to truncate text with ellipsis when it overflows.
`weight`	`string`	`—`	Font weight: one of light, regular, medium, bold.
`wrap`	`string`	`—`	Text wrapping: one of wrap, nowrap, pretty, balance.

align Text alignment: one of left, center, right.

Type string Default —

as The element to render. h1-h6.

Type string Default "h1"

class Additional CSS classes.

Type string Default nil

color Color utility class string. One of: gray, gold, bronze, brown, yellow, amber, orange, tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, lime, mint, sky.

Type string Default —

high_contrast Whether to increase color contrast with the background.

Type boolean Default —

m Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`

Type any Default —

mb Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`

Type any Default —

ml Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`

Type any Default —

mr Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`

Type any Default —

mt Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`

Type any Default —

mx Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`

Type any Default —

my Margin utility class string or map. Example: `1` or `%{xs: '1', sm: '2'}`

Type any Default —

size Heading size (1-9). Responsive supported.

Type string Default —

style Additional inline styles.

Type string Default nil

trim Trim leading space: one of normal, start, end, both.

Type string Default —

truncate Whether to truncate text with ellipsis when it overflows.

Type boolean Default —

weight Font weight: one of light, regular, medium, bold.

Type string Default —

wrap Text wrapping: one of wrap, nowrap, pretty, balance.

Type string Default —

Examples

As another element

Use the as prop to change the heading level. This prop is purely semantic and does not change the visual appearance.

Level 1

Level 2

Level 3

<.flex direction="column" gap="2">
  <.heading as="h1">Level 1</.heading>
  <.heading as="h2">Level 2</.heading>
  <.heading as="h3">Level 3</.heading>
</.flex>

Size

Use the size prop to control the size of the heading. The prop also provides correct line height and corrective letter spacing—as text size increases, the relative line height and letter spacing decrease.

Heading sizes match Text sizes. However, the line heights are set a bit tighter as headings tend to be shorter than running text.

The quick brown fox jumps over the lazy dog

<.flex direction="column" gap="3">
  <.heading size="1">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="2">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="3">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="4">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="5">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="6">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="7">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="8">The quick brown fox jumps over the lazy dog</.heading>
  <.heading size="9">The quick brown fox jumps over the lazy dog</.heading>
</.flex>

Weight

Use the weight prop to set the text weight.

The quick brown fox jumps over the lazy dog.

<.flex direction="column" gap="3">
  <.heading weight="regular">The quick brown fox jumps over the lazy dog.</.heading>
  <.heading weight="medium">The quick brown fox jumps over the lazy dog.</.heading>
  <.heading weight="bold">The quick brown fox jumps over the lazy dog.</.heading>
</.flex>

Align

Use the align prop to set text alignment.

Left-aligned

Center-aligned

Right-aligned

<.box width="100%">
  <.heading align="left">Left-aligned</.heading>
  <.heading align="center">Center-aligned</.heading>
  <.heading align="right">Right-aligned</.heading>
</.box>

Trim

Use the trim prop to trim the leading space at the start, end, or both sides of the text box.

The prop works similarly to the upcoming half-leading control spec, but uses a common negative margin workaround under the hood for cross-browser support.

Without trim

With trim

<.flex direction="column" gap="3">
  <.heading
    trim="normal"
    style="background: var(--gray-a2); border-top: 1px dashed var(--gray-a7); border-bottom: 1px dashed var(--gray-a7);"
  >
    Without trim
  </.heading>
  <.heading
    trim="both"
    style="background: var(--gray-a2); border-top: 1px dashed var(--gray-a7); border-bottom: 1px dashed var(--gray-a7);"
  >
    With trim
  </.heading>
</.flex>

Trimming the leading is useful when dialing in vertical spacing in cards or other "boxy" components. Otherwise, padding looks larger on top and bottom than on the sides.

Without trim

The goal of typography is to relate font size, line height, and line width in a proportional way that maximizes beauty and makes reading easier and more pleasant.

With trim

The goal of typography is to relate font size, line height, and line width in a proportional way that maximizes beauty and makes reading easier and more pleasant.

<.flex direction="column" gap="3">
  <.box p="4" style="background: var(--gray-a2); border: 1px dashed var(--gray-a7);">
    <.heading mb="1" size="3">Without trim</.heading>
    <.text>
      The goal of typography is to relate font size, line height, and line width in a proportional way that maximizes beauty and makes reading easier and more pleasant.
    </.text>
  </.box>
  <.box p="4" style="background: var(--gray-a2); border: 1px dashed var(--gray-a7);">
    <.heading mb="1" size="3" trim="start">With trim</.heading>
    <.text trim="end">
      The goal of typography is to relate font size, line height, and line width in a proportional way that maximizes beauty and makes reading easier and more pleasant.
    </.text>
  </.box>
</.flex>

Truncate

Use the truncate prop to truncate text with an ellipsis when it overflows its container.

The quick brown fox jumps over the lazy dog

<.flex max_width="300px">
  <.heading truncate>The quick brown fox jumps over the lazy dog</.heading>
</.flex>

Wrap

Use the wrap prop to control text wrapping.

The quick brown fox jumps over the lazy dog

<.flex direction="column" gap="3" max_width="300px">
  <.heading wrap="nowrap">The quick brown fox jumps over the lazy dog</.heading>
  <.heading wrap="balance">The quick brown fox jumps over the lazy dog</.heading>
  <.heading wrap="pretty">The quick brown fox jumps over the lazy dog</.heading>
</.flex>

Color

Use the color prop to assign a specific color. The text colors are designed to achieve at least Lc 60 APCA contrast over common background colors.

The quick brown fox jumps over the lazy dog

<.flex direction="column">
  <.heading color="indigo">The quick brown fox jumps over the lazy dog</.heading>
  <.heading color="cyan">The quick brown fox jumps over the lazy dog</.heading>
  <.heading color="orange">The quick brown fox jumps over the lazy dog</.heading>
  <.heading color="crimson">The quick brown fox jumps over the lazy dog</.heading>
</.flex>

High-contrast

Use the high_contrast prop to increase color contrast with the background.

The quick brown fox jumps over the lazy dog.

<.flex direction="column">
  <.heading color="gray">The quick brown fox jumps over the lazy dog.</.heading>
  <.heading color="gray" high_contrast>The quick brown fox jumps over the lazy dog.</.heading>
</.flex>