3.3.3 • Published 5 months ago

react-headings v3.3.3

Weekly downloads
81
License
MIT
Repository
github
Last release
5 months ago

React Headings Logo

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:

Table of contents

Demos

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

Installation

npm install react-headings

Examples

Basic usage

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

function App() {
  return (
    <Section component={<H>My hx</H>}>
      <div>...</div>
      <div>...</div>
      <div>...</div>
      <Section component={<H>My hx+1</H>}>
        <div>...</div>
        <div>...</div>
        <div>...</div>
      </Section>
    </Section>
  );
}

Advanced structure

Child components inherit the current level of their parent:

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

function ParentComponent() {
  return (
    <Section component={<H>My hx</H>}>
      <Section component={<H>My hx+1</H>}>
        <Section component={<H>My hx+2</H>}>
          <ChildComponent />
        </Section>
      </Section>
    </Section>
  );
}

function ChildComponent() {
  return (
    <Section component={<H>My hy</H>}>
      {/* The following heading would be a <h5> in the current context */}
      <Section component={<H>My hy+1</H>}>
        <p>...</p>
      </Section>
    </Section>
  );
}

Styling

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

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

function App() {
  return (
    <Section component={<H className="my-class">My hx</H>}>
      ...
    </Section>
  );
}

Custom heading

A heading can be as complex as we want:

import React from "react";
import { H, Section } from "react-headings";
import MyIcon from "./MyIcon";

function App() {
  return (
    <Section
      component={
        <div className="my-div">
          <MyIcon className="my-icon" />
          <H className="my-heading">My hx</H>
        </div>
      }
    >
      <div>...</div>
      <div>...</div>
      <div>...</div>
    </Section>
  );
}

Using component libraries

Leveraging Component and level from the context allows the use of component libraries. Here's an example with Material UI:

import React from "react";
import { useLevel } from "react-headings";
import { Typography } from "@material-ui/core";

function MyHeading(props) {
  const { Component } = useLevel();

  return <Typography component={Component} {...props} />;
}

API

<H> component

Renders a <h1>, <h2>, <h3>, <h4>, <h5> or <h6> depending on the current level.

Props

NameTypeRequiredDescription
renderfunctionNoOverride with a custom heading. Has precedence over children.
childrennodeNoThe content of the heading. Usually the title.

Any other props will be passed to the heading element.

Example

import React from "react";
import { H } from "react-headings";

function Example1() {
  return <H>This is my title</H>;
}

function Example2() {
  return (
    <H render={({ level, Component }) => <Component>My h{level}</Component>} />
  );
}

<Section> component

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

Props

NameTypeRequiredDescription
componentnodeYesThe heading component. Can be anything but best used in combination with <H>.
childrennodeNoThe content of the new level.

Example

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

function Example1() {
  return (
    <Section component={<H>This is my title</H>}>
      This is my content
    </Section>
  );
}

function Example2() {
  return (
    <Section
      component={
        <div>
          <div>
            <H>This is my title</H>
          </div>
        </div>
      }
    >
      This is my content
    </Section>
  );
}

useLevel hook

Returns an object containing the current level and current Component.

Arguments

None

Returns

NameTypeDescription
level1 | 2 | 3 | 4 | 5 | 6The current level.
Component"h1" | "h2" | "h3" | "h4" | "h5" | "h6"The current component. Same as level.

Example

import React from "react";
import { useLevel } from "react-headings";

function Example(props) {
  const { level, Component } = useLevel();

  return <Component {...props}>This is a h{level}</Component>;
}

Changelog

For a list of changes and releases, see the changelog.

Contributing

Found a bug, have a question or looking to improve react-headings? Open an issue, start a discussion or submit a PR!

3.3.3

5 months ago

3.3.1

9 months ago

3.3.0

10 months ago

3.3.2

9 months ago

3.2.15

1 year ago

3.2.14

1 year ago

3.2.13

1 year ago

3.2.12

1 year ago

3.2.11

2 years ago

3.2.9

2 years ago

3.2.8

2 years ago

3.2.7

2 years ago

3.2.10

2 years ago

3.2.6

2 years ago

3.2.5

2 years ago

3.2.4

2 years ago

3.2.3

2 years ago

3.2.2

2 years ago

3.2.1

3 years ago

3.2.0

3 years ago

3.1.3

3 years ago

3.1.2

3 years ago

3.1.1

3 years ago

3.0.25

3 years ago

3.1.0

3 years ago

3.0.23

3 years ago

3.0.24

3 years ago

3.0.21

3 years ago

3.0.22

3 years ago

3.0.20

3 years ago

3.0.18

3 years ago

3.0.19

3 years ago

3.0.16

4 years ago

3.0.17

4 years ago

3.0.15

4 years ago

3.0.13

4 years ago

3.0.14

4 years ago

3.0.12

4 years ago

3.0.11

4 years ago

3.0.9

4 years ago

3.0.10

4 years ago

3.0.8

4 years ago

3.0.7

4 years ago

3.0.6

4 years ago

3.0.5

4 years ago

3.0.4

4 years ago

3.0.3

4 years ago

3.0.2

4 years ago

3.0.1

4 years ago

3.0.0-next.3

4 years ago

3.0.0

4 years ago

3.0.0-next.2

4 years ago

3.0.0-next.1

4 years ago

2.1.5-next.2

5 years ago

2.1.5-next.1

5 years ago

2.1.4

5 years ago

2.1.3

5 years ago

2.1.2

5 years ago

2.1.0

5 years ago

2.0.0

5 years ago

1.0.9

5 years ago

1.0.8

5 years ago

1.0.6

5 years ago

1.0.4

5 years ago

1.0.3

5 years ago

1.0.2

5 years ago

1.0.0

5 years ago