Skip to content
lib components / Text

Heading

Use this component for titles of pages and page sections.

ExamplesPropertiesGuidelines
import { H1, H2, H3, H4, H5, H6 } from "@siteimprove/fancylib";

When you have multiple consecutive typographic components (headings, paragraphs and lists), wrap them in the text-container component. The text-container component will automatically add the correct spacing between the typographic components.

#Examples

The heading component supports the visual and content hierarchy of a page. This helps users scan a page, get an overview of its content, and navigate it.

The heading component features a few properties for customizing its appearance. The following sections showcase the properties and explain when to use them.

#Default

This is the default appearance of the six heading levels.

Heading 1


Heading 2


Heading 3


Heading 4


Heading 5

Heading 6
<H1>Heading 1</H1> <br /> <H2>Heading 2</H2> <br /> <H3>Heading 3</H3> <br /> <H4>Heading 4</H4> <br /> <H5>Heading 5</H5> <br /> <H6>Heading 6</H6>

#Hook

Headings can also be retrieved from a hook.

Heading from hook

useHeading("h1", { children: "Heading from hook" })

#Heading that looks like an other heading

Headings should be nested according to their level and heading levels should never be skipped. In other words, a heading of a certain level should always be followed by a heading of either the same level or one below (e.g. an h2 should be followed by another h2 or an h3). This creates a clear visual hierarchy and helps assistive technology users understand and navigate a page's content

However, sometimes you want a heading to look like an other heading, for aesthetic reasons. The lookalike property enables you to do this, without sacrificing accessibility. So, if you want an H3 component to be an h3 in code, but look like an H5, you just give the lookalike property of the H3 component the value "h5". The result can be seen below.

Be aware, though, that overuse of this feature will result in visual inconsistency in our UI. This will make the visual appearance of our headings less meaningful to our sighted users.

Heading 1, looks like heading 5

<H1 lookalike="h5">Heading 1, looks like heading 5</H1>

#Alignment

Use this property to center or right align the text in headings. Use it sparingly, since it negatively affects readability.

This heading is left aligned


This heading is center aligned


This heading is right aligned

<H1 alignment="left">This heading is left aligned</H1> <br /> <H1 alignment="center">This heading is center aligned</H1> <br /> <H1 alignment="right">This heading is right aligned</H1>

#Line-height

This property is by default set to multi-line, since headings may wrap across multiple lines. In certain cases, it is certain that a heading will fit on a single line and the "extra" vertical height might be unwanted layout-wise. To support these cases, the property can be set to single-line.

Headings should never be this long, but this example is meant to illustrate how a line height that is larger than the font size prevents the lines from sticking together.


As you can see, a line height that is equal to the font size results in lines that stick together, which negatively impacts the reading experience.

<H2> Headings should never be this long, but this example is meant to illustrate how a line height that is larger than the font size prevents the lines from sticking together. </H2> <br /> <H2 lineHeight="single-line"> As you can see, a line height that is equal to the font size results in lines that stick together, which negatively impacts the reading experience. </H2>

#Tooltip

To use a tooltip for a heading you must use the tooltipText prop to ensure proper accessibility. Do not add the Tooltip component as a child element of the Heading component.

If you need to change the placement of the tooltip you can use the tooltipPlacement prop.

Heading 1

<H1 tooltipText="Tooltip text for a heading" tooltipPlacement="bottom"> Heading 1 </H1>

#Properties

Heading

PropertyDescriptionDefinedValue
idOptional
stringCustom unique id
childrenOptional
ReactNodeContent to be displayed
alignmentOptional
"center" | "left" | "right"Controls vertical alignment
lineHeightOptional
"multi-line" | "single-line"Controls line-height
lookalikeOptional
"h1" | "h2" | "h3" | "h4" | "h5" | "h6"Allows you to specify another kind of header it should LOOK like. It will still be the same header level regardless semantically.
tooltipTextOptional
| string | number | element
tooltipPlacementOptional
"bottom" | "bottom-end" | "bottom-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start"
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Guidelines

#Best practices

  • Use for titles of pages and page sections. For instance, if a card contains multiple charts, then label each of them with an H3 heading (the page will automatically have an H1 and the card an H2)
  • Use to support the visual and content hierarchy of the page. This helps users scan a page, get an overview of its content, and navigate it.
  • Place at the top of the page or page section they belong to.
  • When you have multiple consecutive typographic components (headings, paragraphs and lists, wrap them in the text container component. The component will automatically add the correct spacing between the typographic components.

#Do not use when

You want to style some text that is not the title of a page or page section.

#Accessibility

Headings should be organized hierarchically, without skipping levels. Properly nested headings greatly help users of assistive technologies understand and navigate the page's content.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Be descriptive. Headings should clearly summarize what users can find on the page or page section.
  • Resist the temptation to come up with “creative” or mysterious names for things - keep in mind that users are mostly just trying to get work done.
  • Keep to a single sentence.
  • Avoid punctuation such as periods, commas, or semicolons.
  • Write in sentence case unless it’s a product name.
  • For the learn component, use unique, verb-led headings to grab users' attention.