Edit this page
[?] Component size, gzipped: 26kb

Heading

Headings are absolutely critical for screen reader users and it's important to correctly set their levels. For example, you should never skip a level (having h2 and not h1 on the same page).

The problem is that levels are a question of context. When you move components with headings around, you need to check if levels still make sense and adjust them if not. That's a lot of mundane work and developers often rather take shortcuts such as using h1 element only.

There is proposal for a native <h> element and document outline algorithm to solve this problem once for all but there is no browser support yet. In meantime, our Heading component uses React Context and implements its own document outline algorithm so developers don't have to think about it.

It is also possible to decouple styles from the underlying h1-h6 DOM elements.

Examples

Heading basic usage

Base Web [L1]

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum fermentum velit ante, ac fringilla nulla pulvinar in. Aenean ut nisi mattis, lobortis purus vel, aliquet ante. In vel viverra lectus. Vivamus a diam faucibus, rutrum quam a, varius felis. Sed pellentesque sodales libero commodo vestibulum. Phasellus convallis gravida tempor. Sed ut bibendum nisl.

Introduction [L2]

Vivamus vehicula justo suscipit, vestibulum nibh eu, faucibus nisi. Aenean molestie sapien nibh, sed sagittis turpis iaculis id. Nam mollis pulvinar ex eget gravida. Pellentesque fringilla odio a consequat condimentum. Curabitur ut auctor mi. Nunc blandit, tellus quis fringilla sollicitudin, risus libero scelerisque lorem, ut sagittis risus ipsum in nisl.

Quotes [L3]

Cras posuere placerat sem sit amet dignissim. Sed pellentesque sagittis sapien at maximus. Ut at gravida lectus. Suspendisse lectus libero, eleifend vestibulum imperdiet ut, rhoncus eu augue. Pellentesque in vulputate lacus, quis molestie lorem. Aenean sit amet blandit nisi. Nullam molestie mi vel quam vehicula, in cursus eros tempus. Sed placerat turpis vestibulum quam suscipit, eget volutpat massa aliquet.

Subtitle [L4]

Proin et posuere lectus. Curabitur condimentum, mauris in viverra euismod, diam elit porttitor quam, ac dictum diam diam eu mauris. Maecenas viverra, turpis sed commodo hendrerit, quam ipsum finibus mauris, et scelerisque sapien tellus mollis leo. Praesent posuere, felis at sagittis hendrerit, est massa tincidunt risus, eget tempus dolor ligula et odio. Praesent luctus lacus quis tristique semper. Etiam semper lacus non auctor fringilla.

Subtitle [L5]

Vivamus vehicula justo suscipit, vestibulum nibh eu, faucibus nisi. Aenean molestie sapien nibh, sed sagittis turpis iaculis id. Nam mollis pulvinar ex eget gravida. Pellentesque fringilla odio a consequat condimentum. Curabitur ut auctor mi. Nunc blandit, tellus quis fringilla sollicitudin, risus libero scelerisque lorem, ut sagittis risus ipsum in nisl.

Subtitle [L6]

Proin et posuere lectus. Curabitur condimentum, mauris in viverra euismod, diam elit porttitor quam, ac dictum diam diam eu mauris. Maecenas viverra, turpis sed commodo hendrerit, quam ipsum finibus mauris, et scelerisque sapien tellus mollis leo. Praesent posuere, felis at sagittis hendrerit, est massa tincidunt risus, eget tempus dolor ligula et odio. Praesent luctus lacus quis tristique semper. Etiam semper lacus non auctor fringilla.

Motivation [L2]

Vivamus vehicula justo suscipit, vestibulum nibh eu, faucibus nisi. Aenean molestie sapien nibh, sed sagittis turpis iaculis id. Nam mollis pulvinar ex eget gravida. Pellentesque fringilla odio a consequat condimentum. Curabitur ut auctor mi. Nunc blandit, tellus quis fringilla sollicitudin, risus libero scelerisque lorem, ut sagittis risus ipsum in nisl.

Ideally, the user will use the default styles but sometimes it might make sense to set a fixed style no matter in what context the component was placed. You can decouple styles from levels through the styleLevel prop. However, the proper h1, h2 ... h6 hiearchy always stays in place.

Decouple and fix heading styles

Base Web [L1 styled as L4]

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum fermentum velit ante, ac fringilla nulla pulvinar in. Aenean ut nisi mattis, lobortis purus vel, aliquet ante. In vel viverra lectus. Vivamus a diam faucibus, rutrum quam a, varius felis. Sed pellentesque sodales libero commodo vestibulum. Phasellus convallis gravida tempor. Sed ut bibendum nisl.

Introduction [L2 styled as L5]

Vivamus vehicula justo suscipit, vestibulum nibh eu, faucibus nisi. Aenean molestie sapien nibh, sed sagittis turpis iaculis id. Nam mollis pulvinar ex eget gravida. Pellentesque fringilla odio a consequat condimentum. Curabitur ut auctor mi. Nunc blandit, tellus quis fringilla sollicitudin, risus libero scelerisque lorem, ut sagittis risus ipsum in nisl.

Quotes [L3 styled as L6]

Cras posuere placerat sem sit amet dignissim. Sed pellentesque sagittis sapien at maximus. Ut at gravida lectus. Suspendisse lectus libero, eleifend vestibulum imperdiet ut, rhoncus eu augue. Pellentesque in vulputate lacus, quis molestie lorem. Aenean sit amet blandit nisi. Nullam molestie mi vel quam vehicula, in cursus eros tempus. Sed placerat turpis vestibulum quam suscipit, eget volutpat massa aliquet.

Motivation [L2 styled as L5]

Proin et posuere lectus. Curabitur condimentum, mauris in viverra euismod, diam elit porttitor quam, ac dictum diam diam eu mauris. Maecenas viverra, turpis sed commodo hendrerit, quam ipsum finibus mauris, et scelerisque sapien tellus mollis leo. Praesent posuere, felis at sagittis hendrerit, est massa tincidunt risus, eget tempus dolor ligula et odio. Praesent luctus lacus quis tristique semper. Etiam semper lacus non auctor fringilla.

API

HeadingLevel API

children Node required

Content to be rendered in the HeadingLevel.

Node

Heading API

styleLevel number

Set and fix the style level independently on the hierarchy context.

children import

react.Node

as import

Modifies the base element used to render the block.

react.ElementType

overrides object

Block { component: ?ComponentType<<T> & { children: Node }>, props: ?{} | ({}) => ?{}, style: ?{} | ({}) => ?{} }<<T>> | ComponentType<<T> & { children: Node }>*

color <T> | Array<<T>><string>

Accepts all themeable color properties (primary200, etc.).

<T> | Array<<T>>string

backgroundAttachment <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/background-attachment

<T> | Array<<T>>string

backgroundClip <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/background-clip

<T> | Array<<T>>string

backgroundColor <T> | Array<<T>><string>

Accepts all themeable color properties (primary200, etc.).

<T> | Array<<T>>string

backgroundImage <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/background-image

<T> | Array<<T>>string

backgroundOrigin <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/background-origin

<T> | Array<<T>>string

backgroundPosition <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/background-position

<T> | Array<<T>>string

backgroundRepeat <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/background-repeat

<T> | Array<<T>>string

backgroundSize <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/background-size

<T> | Array<<T>>string

font union

Accepts all themeable font properties (font200, etc.).

One of
string,
Arraystring

alignContent <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/align-content

<T> | Array<<T>>One of
"center",
"start",
"end",
"flex-start",
"flex-end",
"normal",
"baseline",
"first baseline",
"last baseline",
"space-between",
"space-around",
"space-evenly",
"stretch",
"safe center",
"unsafe center",
"inherit",
"initial",
"unset"

alignItems <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/align-items

<T> | Array<<T>>One of
"normal",
"stretch",
"center",
"start",
"end",
"flex-start",
"flex-end",
"self-start",
"self-end",
"baseline",
"first baseline",
"last baseline",
"safe center",
"unsafe center",
"inherit",
"initial",
"unset"

alignSelf <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/align-self

<T> | Array<<T>>One of
"auto",
"normal",
"center",
"start",
"end",
"self-start",
"self-end",
"flex-start",
"flex-end",
"baseline",
"first baseline",
"last baseline",
"stretch",
"safe center",
"unsafe center",
"inherit",
"initial",
"unset"

flexDirection <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction

<T> | Array<<T>>One of
"row",
"row-reverse",
"column",
"column-reverse",
"inherit",
"initial",
"unset"

display <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/display

<T> | Array<<T>>One of
"block",
"inline",
"run-in",
"flow",
"flow-root",
"table",
"flex",
"grid",
"ruby",
"block flow",
"inline table",
"flex run-in",
"list-item",
"list-item block",
"list-item inline",
"list-item flow",
"list-item flow-root",
"list-item block flow",
"list-item block flow-root",
"flow list-item block",
"table-row-group",
"table-header-group",
"table-footer-group",
"table-row",
"table-cell",
"table-column-group",
"table-column",
"table-caption",
"ruby-base",
"ruby-text",
"ruby-base-container",
"ruby-text-container",
"contents",
"none",
"inline-block",
"inline-table",
"inline-flex",
"inline-grid",
"inherit",
"initial",
"unset"

flex <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/flex

<T> | Array<<T>>One of
number,
string

grid <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid

<T> | Array<<T>>string

gridArea <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-area

<T> | Array<<T>>string

gridAutoColumns <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-columns

<T> | Array<<T>>string

gridAutoFlow <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-flow

<T> | Array<<T>>One of
"row",
"column",
"dense",
"row dense",
"column dense",
"inherit",
"initial",
"unset"

gridAutoRows <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-rows

<T> | Array<<T>>string

gridColumn <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column

<T> | Array<<T>>string

gridColumnEnd <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-end

<T> | Array<<T>>string

gridColumnGap <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-gap

<T> | Array<<T>>One of
0,
string

gridColumnStart <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-column-start

<T> | Array<<T>>string

gridGap <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-gap

<T> | Array<<T>>One of
0,
string

gridRow <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row

<T> | Array<<T>>string

gridRowEnd <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-end

<T> | Array<<T>>string

gridRowGap <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-gap

<T> | Array<<T>>One of
0,
string

gridRowStart <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-row-start

<T> | Array<<T>>string

gridTemplate <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template

<T> | Array<<T>>string

gridTemplateAreas <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-areas

<T> | Array<<T>>string

gridTemplateColumns <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns

<T> | Array<<T>>string

gridTemplateRows <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-rows

<T> | Array<<T>>string

justifyContent <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content

<T> | Array<<T>>One of
"center",
"start",
"end",
"flex-start",
"flex-end",
"left",
"right",
"space-between",
"space-around",
"space-evenly",
"stretch",
"safe center",
"unsafe center",
"inherit",
"initial",
"unset"

justifyItems <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items

<T> | Array<<T>>One of
"auto",
"normal",
"stretch",
"center",
"start",
"end",
"flex-start",
"flex-end",
"self-start",
"self-end",
"left",
"right",
"baseline",
"first baseline",
"last baseline",
"safe center",
"unsafe center",
"legacy right",
"legacy left",
"legacy center",
"inherit",
"initial",
"unset"

justifySelf <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/justify-self

<T> | Array<<T>>One of
"auto",
"normal",
"stretch",
"center",
"start",
"end",
"flex-start",
"flex-end",
"self-start",
"self-end",
"left",
"right",
"baseline",
"first baseline",
"last baseline",
"safe center",
"unsafe center",
"inherit",
"initial",
"unset"

position <T> | Array<<T>><union>

<T> | Array<<T>>One of
"static",
"absolute",
"relative",
"fixed",
"sticky"

width <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

minWidth <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

maxWidth <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

height <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

minHeight <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

maxHeight <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

overflow <T> | Array<<T>><union>

<T> | Array<<T>>One of
"visible",
"hidden",
"scroll",
"scrollX",
"scrollY",
"auto",
"inherit",
"initial",
"unset"

margin <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

marginTop <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

marginRight <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

marginBottom <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

marginLeft <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

padding <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

paddingTop <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

paddingRight <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

paddingBottom <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

paddingLeft <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

placeContent <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/place-content

<T> | Array<<T>>string

placeItems <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/place-items

<T> | Array<<T>>string

placeSelf <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/place-self

<T> | Array<<T>>string

flexWrap <T> | Array<<T>><boolean>

<T> | Array<<T>>boolean

left <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

top <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

right <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

bottom <T> | Array<<T>><union>

<T> | Array<<T>>One of
0,
string

textOverflow <T> | Array<<T>><string>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/text-overflow

<T> | Array<<T>>string

whiteSpace <T> | Array<<T>><union>

available values: https://developer.mozilla.org/en-US/docs/Web/CSS/white-space

<T> | Array<<T>>One of
"normal",
"nowrap",
"pre",
"pre-wrap",
"pre-line",
"break-spaces",
"inherit",
"initial",
"unset"