Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/alexnault/react-headings

⚛ Auto-increment your HTML headings (h1, h2, etc.) for improved accessibility and SEO.
https://github.com/alexnault/react-headings

a11y accessibility h1 heading headings react seo wcag

Last synced: 2 months ago
JSON representation

⚛ Auto-increment your HTML headings (h1, h2, etc.) for improved accessibility and SEO.

Lists

README 

        
![React Headings Logo](https://github.com/alexnault/react-headings/raw/master/assets/react-headings.png)



# React Headings





  

    

  

  

    

  

  

    

  

  

    

  




> Never worry about using the wrong heading level (`h1`, `h2`, etc.) in complex React apps!



React-headings maintains the proper hierarchy of headings for improved accessibility and SEO, no matter the component structure, while you keep full control of what's rendered.



References:



- [WCAG 2.0 technique H69](https://www.w3.org/TR/WCAG20-TECHS/H69.html)

- [Lighthouse SEO heading order audit](https://web.dev/heading-order/)



## Table of contents



- [Demos](#demos)

- [Highlights](#highlights)

- [Installation](#installation)

- [Examples](#examples)

- [API](#api)

- [Changelog](#changelog)

- [Contributing](#contributing)



## Demos



- [Minimal](https://codesandbox.io/s/react-headings-minimal-4temt?file=/src/Demo.js)

- [Custom component](https://codesandbox.io/s/react-headings-custom-component-l4bjb?file=/src/Demo.js)

- [Advanced structure](https://codesandbox.io/s/react-headings-advanced-structure-uxk4p?file=/src/Demo.js)



## Highlights



- Improves SEO and accessibility

- Supports server-side rendering

- Under 1 kB minified & gzipped

- Typed with TypeScript

- Fully tested

- Works with any CSS solutions (Tailwind, CSS-in-JS, etc.)

- Plays nicely with component libraries (Material UI, etc.)

- Follows [semantic versioning](https://semver.org/)



## Installation



```bash

npm install react-headings

```



## Examples



### Basic usage



```jsx

import React from "react";

import { H, Section } from "react-headings";



function App() {

  return (

    My hx}>

      
...


      
...


      
...


      My hx+1}>

        
...


        
...


        
...


      

    

  );

}

```



### Advanced structure



Child components inherit the current level of their parent:



```jsx

import React from "react";

import { H, Section } from "react-headings";



function ParentComponent() {

  return (

    My hx}>

      My hx+1}>

        My hx+2}>

          

        

      

    

  );

}



function ChildComponent() {

  return (

    My hy}>

      {/* The following heading would be a 
 in the current context */}

      My hy+1}>

        
...


      

    


  );

}

```



### Styling



A heading can be styled like any ordinary `` element since it accepts all the same props:



```jsx

import React from "react";

import { H, Section } from "react-headings";



function App() {

  return (

    My hx}>

      ...

    

  );

}

```



### Custom heading



A heading can be as complex as we want:



```jsx

import React from "react";

import { H, Section } from "react-headings";

import MyIcon from "./MyIcon";



function App() {

  return (

    

          

          My hx

        

      }

    >

      
...


      
...


      
...


    

  );

}

```



### Using component libraries



Leveraging `Component` and `level` from the context allows the use of component libraries.

Here's an example with [Material UI](https://material-ui.com/api/typography/):



```jsx

import React from "react";

import { useLevel } from "react-headings";

import { Typography } from "@material-ui/core";



function MyHeading(props) {

  const { Component } = useLevel();



  return ;

}

```



## API



### `` component



Renders a `
`, `
`, `
`, `
`, `
` or `
` depending on the current level.



#### Props



| Name       | Type       | Required | Description                                                     |

| ---------- | ---------- | -------- | --------------------------------------------------------------- |

| `render`   | `function` | No       | Override with a custom heading. Has precedence over `children`. |

| `children` | `node`     | No       | The content of the heading. Usually the title.                  |



Any other props will be passed to the heading element.



#### Example



```jsx

import React from "react";

import { H } from "react-headings";



function Example1() {

  return This is my title;

}



function Example2() {

  return (

     My h{level}} />

  );

}

```



### `` component



Creates a new section (a heading and its level).



#### Props



| Name        | Type   | Required | Description                                                                     |

| ----------- | ------ | -------- | ------------------------------------------------------------------------------- |

| `component` | `node` | Yes      | The heading component. Can be anything but best used in combination with ``. |

| `children`  | `node` | No       | The content of the new level.                                                   |



#### Example



```jsx

import React from "react";

import { Section, H } from "react-headings";



function Example1() {

  return (

    This is my title}>

      This is my content

    

  );

}



function Example2() {

  return (

    

          


            This is my title

          


        

      }

    >

      This is my content

    

  );

}

```



### `useLevel` hook



Returns an object containing the current `level` and current `Component`.



#### Arguments



None



#### Returns



| Name        | Type                                                     | Description                           |

| ----------- | -------------------------------------------------------- | ------------------------------------- |

| `level`     | `1` \| `2` \| `3` \| `4` \| `5` \| `6`                   | The current level.                    |

| `Component` | `"h1"` \| `"h2"` \| `"h3"` \| `"h4"` \| `"h5"` \| `"h6"` | The current component. Same as level. |



#### Example



```jsx

import React from "react";

import { useLevel } from "react-headings";



function Example(props) {

  const { level, Component } = useLevel();



  return This is a h{level};

}

```



## Changelog



For a list of changes and releases, see the [changelog](https://github.com/alexnault/react-headings/releases).



## Contributing



Found a bug, have a question or looking to improve react-headings? Open an [issue](https://github.com/alexnault/react-headings/issues/new), start a [discussion](https://github.com/alexnault/react-headings/discussions/new) or submit a [PR](https://github.com/alexnault/react-headings/fork)!