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: about 2 months ago
JSON representation
⚛ Auto-increment your HTML headings (h1, h2, etc.) for improved accessibility and SEO.
- Host: GitHub
- URL: https://github.com/alexnault/react-headings
- Owner: alexnault
- License: mit
- Created: 2020-12-31T18:10:28.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-09-28T18:28:56.000Z (3 months ago)
- Last Synced: 2024-09-28T18:30:50.106Z (3 months ago)
- Topics: a11y, accessibility, h1, heading, headings, react, seo, wcag
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-headings
- Size: 1.69 MB
- Stars: 75
- Watchers: 2
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-react-components - react-headings - Auto-increment your HTML headings (h1, h2, etc.) for improved accessibility and SEO, no matter your component structure, while you keep full control of what's rendered. (UI Components / Miscellaneous)
- awesome-react-components - react-headings - Auto-increment your HTML headings (h1, h2, etc.) for improved accessibility and SEO, no matter your component structure, while you keep full control of what's rendered. (UI Components / Miscellaneous)
- fucking-awesome-react-components - react-headings - Auto-increment your HTML headings (h1, h2, etc.) for improved accessibility and SEO, no matter your component structure, while you keep full control of what's rendered. (UI Components / Miscellaneous)
README
# 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)!