react-accessible-headings

Why?

In order to make accessible web pages the W3C: WCAG, WAI say,

> Skipping heading ranks can be confusing and should be avoided where possible: Make sure that a

is not followed directly by an

, for example.

So an accessible app must not have heading levels like this...

- H1
- H6
- H3
- H1 (there should only be a single H1!)
- H5
- H4
- H4
- H1

Instead they should look like,

- H1
- H2
- H3
- H3
- H2
- H3
- H4
- H4
- H2

Why a React library?

However as developers of React components it's hard to make components match this semantic hierarchy. We typically hardcode heading levels, like an

, or an

, into a component. This would limit its flexibility and make it harder to adhere to W3C WCAG.

By using react-accessible-headings you can have components with flexible headings that fit the appropriate heading level, allowing you to more easily create accessible components, with headings that don't skip levels.

Could you instead write components that accept props to set a heading level? Sure. But that requires manual maintenance of the hierarchy. Indenting becomes harder, and it's easier to make mistakes.

This library is 1 kilobyte (minified and compressed).

Usage

``jsx
import React from 'react';
import { Level, H } from 'react-accessible-headings';

export default function () {
return (



This will be a heading 1

and this a Heading 2




);
}
`

$3

react-accessible-headings tries to encourage correct heading levels by polling the DOM for accessibility errors and printing errors to console.error. These errors are page-wide and not necessarily specific to react-accessible-headings.

There are two types of errors that are checked

1. Whether there are skipped heading levels. Ie,

followed by an

;
2. Whether there are multiple

s in the page (there should only be a single

).

A console.error() will be printed if an error occurs.

Testing in Axe will also reveal this type of error.

The reason this was implemented by polling the DOM, rather than analysing the React VDOM (or something), is because only the real DOM knows the actual heading levels that screen readers will use for accessibility reasons. Pages could include headings outside of React apps that affect the heading level, so this library needs to poll the DOM.

API

All APIs have TypeScript types available.

$3

This component renders either

,

,

,

,

, or

based on how many s were above it.

react-accessible-headings tries to help you maintain valid heading hierarchies, so it considers it an application bug to render an (the HTML spec only has 6 heading levels). This might happen if you have too many s above it.

To help debug the error a message will printed via console.error if attempting to render invalid levels such as h7. To resolve this error fix the wrongly nested elements above it.

All valid props / attributes for an HTML heading are also accepted.

Props: offset: _(Optional)_ this optional prop will override the default behaviour. The default behaviour is when you use without this prop it will render the current heading level depth. If instead you want to render the with a different offset (number) then provide this prop.

See _Examples: The 'Offset' Example_ for more.

$3

Sets a new heading level depth, by incrementing the current heading level for all children using the component, or the useLevel hook.

This component doesn't render anything except children, so there's no wrapper element.

Props: value: _(Optional)_ this optional prop will override the default behaviour. The default behaviour is when you use without this prop it will increment the heading level by 1. If you want to increment by a different value (number) that is not 1 then provide this value prop. You probably shouldn't be using this.
Props: hClassName: _(Optional)_ this optional prop will set a className on all descendant s.

An error will be logged via console.error if attempting to set an invalid value such as 7, because HTML only has h1-h6.

$3

If you'd like to inspect the current level context value then useLevel() which will return a number (integer) from 1-6. (see _Examples: The 'useLevel query' Example_ for more).

An error will be logged via console.error if useLevel resolves to an invalid heading level such as 7 and the value will be clamped from 1-6 (because 7 is an invalid heading level and it would be pointless to use that).

$3

If for some reason you'd like to inspect the current hClassName value, then useHClassName() which will return a string representing the className of the Heading elements in the current tree (see _Examples: The 'useHClassName' Example_ for more).

$3

Provides direct access to the React Context which is an object with type undefined | { level: number, hClassName?: string }. Note that the value may be undefined in which case you should infer a level of 1. No clamping of valid ranges of values occurs through this direct accesss.

Further reading

$3

DocBook, the ill-fated XHTML 2, and HTML5's abandoned 'outline' had a very similar idea. Also check out the 2014 project html5-h.

$3

#### WCAG 2: G141: Organizing a page using headings,

> To facilitate navigation and understanding of overall document structure, authors should use headings that are properly nested (e.g., h1 followed by h2, h2 followed by h2 or h3, h3 followed by h3 or h4, etc.).

#### Axe: Heading levels should only increase by one

> Ensure headings are in a logical order. For example, check that all headings are marked with h1 through h6 elements and that these are ordered hierarchically. For example, the heading level following an h1 element should be an h2 element, not an h3 element.

##### Axe: Page must contain a level-one heading

> Generally, it is a best practice to ensure that the beginning of a page's main content starts with a h1 element, and also to ensure that the page contains only one h1 element.

Justifications #

Is this library necessary? Could you avoid this library and perhaps make component props that set the heading level, or use children to set the heading? Sure, that works, but (arguably) that manual approach becomes a maintenance problem across a larger app. Across a whole app this alternative approach is easier to refactor and 'indent' heading levels arbitrarily without having to synchronise the correct heading level numbers across components.

$3

Imagine you have a hypothetical 'Card' component that is coded as,

`jsx
export function Card({ children, heading }) {
return (


{heading}

{children}


);
}
`

But then you want to make the

configurable to make it either an

,

, or

.

You might refactor the code to support that feature like this,

`jsx
export function Card({ children, heading, headingLevel }) {
return (


{headingLevel === 2 ? (

{heading}

) : headingLevel === 3 ? (

{heading}

) : headingLevel === 4 ? (

{heading}

) : null}
{children}


);
}
`

or more concisely,

`jsx
export function Card({ children, heading, headingLevel }) {
const Heading = H${headingLevel};
return (



{heading}
{children}



);
}
`

...which is a confusingly indirect way of making a heading level, and it creates a maintenance burden on developers to know the correct level depth of a heading.

Alternatively, with react-accessible-headings the implementation details of can stay encapsulated and look like,

`jsx
export function Card({ children, heading }) {
return (



{heading}
{children}



);
}
`

And finally (for this example) let's consider another refactoring. If we want to add a new h2 to the page and lower every other heading it's now easy to add another wrapper to indent everything and you're done. Much easier than updating lots of h* numbers around the code to realign them all...

`jsx
Cards




body

body

`

So react-accessible-headings is an alternative composition technique for page headings that may make it easier to refactor and reuse code. The concept means you only need to think about whether it's a deeper level, without having to know the specific heading level number.

That all said, having a flexible heading level may be more abstract and confusing to some developers. It's an extra thing to learn, even though it is a simple concept. It may not be appropriate for some codebases.

$3

If you want to programatically query the current level you can,

`jsx
import { useLevel, H } from 'react-accessible-headings';

export default function () {
const level = useLevel(); // level is a number (integer) from 1-6
return (


heading--${level}}>
text



);
}
`

$3

If you want to have heading levels relative to the current level you can provide an offset prop,

`jsx



This will be the current heading level

This will be one level deeper

{children}



`

which is a more concise way of writing this,

`jsx



This will be the current heading level

This will be one level deeper

{children}



`

However will establish a new deeper _heading level_ context whereas offset will not.

$3

If you ever need to style multiple headings with css, you might find that your highly composable React code (for a good reason)
hides the heading selectors from you:

`css
.card h{???} {
margin-top: 2em;
}
`

In this case you can set className on every element and use the class selector in CSS, or as a shorthand you can provide hClassName prop to a element, which will set your className on every decendant heading element in the sub-tree:

`jsx

My ClassName is heading
My ClassName is heading custom

My ClassName is also heading

Mine changed to card-heading



`

$3

This example shows how you can utilize useHClassName to extend hClassName instead of overriding it.

`jsx
import { useHClassName, Level } from 'react-accessible-headings';

function Nested() {
const hClassName = useHClassName(); // className declared by parent
return ${hClassName}__with-bem-syntax}>...;
}



;
// hClassName changed to "heading__with-bem-syntax"
``