Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
55 lines (37 sloc) 2.28 KB

import Example from '../../components/example'; import API from '../../components/api'; import Layout from '../../components/layout';

import Basic from 'examples/heading/basic.js'; import DecoupleStyles from 'examples/heading/decouple-styles.js';

import {Heading, HeadingLevel} from 'baseui/heading';

export default Layout;


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.


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.

<Example title="Decouple and fix heading styles" path="heading/decouple-styles.js"


<API heading="HeadingLevel API" api={require('!!@uber-web-ui/extract-react-types-loader!../../../src/heading/heading-level.js')} />

<API heading="Heading API" api={require('!!@uber-web-ui/extract-react-types-loader!../../../src/heading/heading.js')} />

You can’t perform that action at this time.