Package Exports

react-accessible-headings

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-accessible-headings) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

react-accessible-headings

The Problem

WCAG WAI says,

Skipping heading ranks can be confusing and should be avoided where possible: Make sure that a <h2> is not followed directly by an <h4>, for example.

However developers often hardcode specific heading levels into their components such as <h1> or <h2>, limiting their flexibility and making it harder to adhere to semantic heading levels.

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 headings that don't skip levels.

Could you avoid this library and perhaps make component props that set the heading level, or use children in each instance so that the heading level is correct? Sure, but this is an alternative approach that makes it easier to refactor and 'indent' heading levels arbitrarily without having to know the correct heading level numbers. See the Examples section for an analysis of the pros and cons of this approach.

This library is less than 1 kilobyte (minified and compressed).

Usage

import React from "react";
import { Level, H } from "react-accessible-headings";

export default function() {
  return (
    <div>
      <H>This will be a heading 1</H>
      <Level>
        <H>and this a Heading 2</H>
      </Level>
    </div>
  );
}

Examples

The 'Card' Example

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

export function Card({ children, heading }) {
  return (
    <div className="card">
      <h1 className="card__heading">{heading}</h1>
      {children}
    </div>
  );
}

But then you want to make the <h1> configurable to make it either an <h1> or an <h2>. The card will be used in two places with two different heading levels.

So you might refactor the code to support that feature like this,

export function Card({ children, heading, headingLevel }) {
  return (
    <div className="card">
      {headingLevel === 1 ? (
        <h1 className="card__heading">{heading}</h1>
      ) : headingLevel === 2 ? (
        <h2 className="card__heading">{heading}</h2>
      ) : null}
      {children}
    </div>
  );
}

or,

export function Card({ children, heading, headingLevel }) {
  return (
    <div className="card">
      {React.createElement(
        "h" + headingLevel,
        { className: "card__heading" },
        heading
      )}
      {children}
    </div>
  );
}

...and now the parent component needs to set the headingLevel number, a confusingly indirect way of making an h1 or h2.

Or, perhaps you'd use children,

export function Card({ children }) {
  return <div className="card">{children}</div>;
}

...but now the parent component needs to know about the "card__heading" className and the implementation details of <Card> are leaking; there's less encapsulation when the usage looks like,

// usage
<Card>
  <h1 className="card__heading">text</h1>
  <p>body</p>
</Card>
<Card>
  <h2 className="card__heading">text</h2>
  <p>body</p>
</Card>

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

export function Card({ children, heading }) {
  return (
    <div className="card">
      <H className="card__heading">{heading}</H>
      {children}
    </div>
  );
}

...while the usage looks like,

// usage
<Card heading="text">
  <p>body</p>
</Card>
<Level>
  <Card heading="text">
    <p>body</p>
  </Card>
</Level>

The <Level> indents all the <H> heading levels inside the <Level>.

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

<H>Cards</H>
<Level>
  <Card heading="text">
    <p>body</p>
  </Card>
  <Level>
    <Card heading="text">
      <p>body</p>
    </Card>
  </Level>
</Level>

So react-accessible-headings is an alternative composition technique for page headings that may make it easier to refactor and reuse code. The <Level> 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.

The 'useLevel query' Example

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

import { useLevel, H } from "react-accessible-headings";

export default function() {
  const level = useLevel(); // level is a number (integer) from 1-6
  return (
    <div className={`heading--${level}`}>
      <H>text</H>
    </div>
  );
}

The 'Offset' Example

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

<div className="card">
  <H className="card__heading">This will be the current heading level</H>
  <H offset={1} className="card__sub-heading">
    This will be one level deeper
  </H>
  {children}
</div>

which is a more concise way of writing this,

<div className="card">
  <H className="card__heading">This will be the current heading level</H>
  <Level>
    <H className="card__sub-heading">This will be one level deeper</H>
  </Level>
  {children}
</div>

However <Level> will establish a new deeper heading level context whereas offset will not.

API

All APIs have TypeScript types available.

`<Level>` component

Props: value: (Optional) a number to override the level. There are no other props, except children.

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

In Development mode an exception will be thrown if attempting to set an invalid value such as 7 as HTML only has h1-h6. In Production mode an error will be logged via console.error.

`<H>` component

Props: offset: (Optional) a number to offset the heading level (see Examples: The 'Offset' Example for more). All other valid props for an heading are also accepted.

This component renders either <h1>, <h2>, <h3>, <h4>, <h5>, or <h6>.

In Development mode an exception will be thrown if attempting to render invalid HTML such as <h7>. In Production mode an error will be logged via console.error.

`useLevel` context hook

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

In Development mode an exception will be thrown if useLevel resolves to an invalid heading level such as 7. In Production mode an error will be logged via console.error.

`LevelContext` context

The raw React Context. Note that the value may be undefined in which case you should infer a level of 1.

Limitations

While this library facilitates dynamic heading levels it doesn't detect skipped heading levels through incorrect usage such as,

<h1>Heading 1</h1>
<Level>
  <Level>
    <Level>
      <H>this will be a heading 4. Levels 2 and 3 were skipped!</H>
    </Level>
  </Level>
</Level>

Testing in Axe will reveal this error. It's unlikely that this project will introduce a runtime check for analysing heading levels as Axe already does this. Also, because webpages could have a static HTML h1 with a React app rendering only h2s (a perfectly valid and accessible approach) then a test would need to analyse the whole DOM and have nothing to do with React in particular or this project. Replicating this Axe functionality would likely be pointless.

JSPM