Heading

Heading renders an h1 to h6 element at a step of the type scale. It names the content that follows it, and screen reader users move through a page by its headings. Copy that only needs to look larger, such as a price or a lead sentence, is Text.

Playground

Usage

import { Button, Card, Flex, Heading, Text } from '@kushagradhawan/kookie-ui';
 
export function BillingCard() {
  return (
    <Card size="2">
      <Flex direction="column" gap="2" align="start">
        <Heading size="4">
          Billing
        </Heading>
        <Text as="p" size="2" emphasis="medium">
          Your next invoice is on 1 March.
        </Text>
        <Button size="2">Manage plan</Button>
      </Flex>
    </Card>
  );
}

Best practices

Set as="h1" on the page title. Heading renders an h2 by default, which fits a section. A page has one h1, and a heading inside a section needs as="h3".

Choose the level for the outline and the size for the look. as and size are separate. A card title can be an h3 at size 4 in one place and an h2 at size 6 in another. Don't skip levels to get a smaller heading.

Write the heading as a label for what follows. "Billing" or "Team members" tells people what the section holds. A full sentence or a question is harder to scan in a list of headings.

Rank headings with emphasis, not with gray. Use emphasis="medium" for a heading that sits below a stronger one, such as a group label in a sidebar. Leave color for a heading that carries a meaning.

Don't use Heading for text that only needs weight. A bold label in a table row or a form is Text with weight="medium". Every Heading adds an entry to the page outline.

Size

size picks a step from 1 to 9: 12, 14, 16, 18, 20, 24, 32, 44 and 64 pixels at the default scale. Size 6 is the default. The theme can adjust heading sizes and spacing with its own heading tokens.

size accepts a responsive object, such as { initial: '6', md: '7' }.

Emphasis

emphasis sets how strongly a heading reads. With no color set, loud, medium and quiet step down the neutral ink. With a color set, the heading reads that colour's strong ink, and medium and quiet fade it. With no color and no emphasis, a heading inherits its colour.

Examples

Page and section titles

Give the page one h1 and its sections h2. Sizes can step down further than the levels.

<Flex direction="column" gap="5">
  <Heading as="h1" size="7">
    Settings
  </Heading>
  <Heading as="h2" size="5">
    Profile
  </Heading>
</Flex>

Centred title over a few lines

wrap="balance" evens out the line lengths, so a centred title doesn't leave one word on the last line.

<Heading
  as="h1"
  size="8"
  align="center"
  wrap="balance"
>
  Plan, build and ship your next release
</Heading>

Title on one line

truncate keeps a long title, such as a file name in a panel header, on one line and ends it with an ellipsis.

<Heading as="h2" size="3" truncate>
  Quarterly report, final version, approved by finance
</Heading>

Title flush with a card edge

trim="start" removes the space above the first line, so the title lines up with the top of the card's padding.

Props

Heading also accepts every attribute of the HTML heading element set by as.

Accessibility

• Level: A screen reader announces the level, such as "heading level 2". People use the levels to jump between sections, so keep them in order without gaps.
• One page title: Use one h1 for each page, set with as="h1". Other headings default to h2.
• Name: A Heading's text names a section. To name a region, point aria-labelledby on the section at the heading's id.
• Truncation: A screen reader reads a truncated heading in full. A pointer user can't see the rest, so add a title when the hidden part matters.