react-anchor-navigation

React lightweight library for anchor scrolling and navigation tied to URL hash.

Features

This library exports multiple helpers designed to make your anchor navigation works seamlessly. Check the examples

Four components :

• AnchorContext
• AnchorLink
• AnchorProvider
• AnchorSection

Getting Started

Installation

This project uses react hooks and is therefore reliant on react version >=16.8.6

To install and use react-anchor-navigation, add it to your package.json and modules with the following command line :

npm install --save react-anchor-navigation

OR

yarn add react-anchor-navigation

Usage

import {
  AnchorContext,
  AnchorLink,
  AnchorProvider,
  AnchorSection,
} from "react-anchor-navigation";

AnchorProvider

AnchorProvider is our top level contextProvider. Wrap it around your topmost component for your view :

<AnchorProvider>
  <YourView />
</AnchorProvider>

| Key | Type | Description | | ----------- | :-----------------: | ---------------------------------------------------------------------------------------------------------------: | | offset | number | The offset amount of pixels from the top, usefull when handling fixed header or sticky navigation (default: 0) | | getScroller | () => HTMLElement | Function to returns the scrollable element (default: body) |

It will provide the AnchorContext to all children.

AnchorContext

AnchorContext is the context you can yield with the new useContext hook or with old-fashioned Context.consumer.

const { hash, sections } = useContext(AnchorContext);

Here is its typing :

| Key | Type | Description | | ----------------- | :---------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------: | | sections | HTMLElement[] | List of the registered sections elements that we watch, in our codebase it is AnchorSection | | hash | string | The registered hash corresponding to our current scroll position | | registerSection | (element: HTMLElement) => void | Function to add a Section to our sections list, our scrollEvent listener will then update the hash if the section is scrolled to | | unregisterSection | (element: HTMLElement) => void | Function to remove a Section to our sections list, our scrollEvent listener will then stop checking this section | | setHash | (hash: string, withScroll?: boolean) => void; | Setter function from the internal useHash hooks, use it to programmatically change the current hash | | offset | number | The offset amount of pixels from the top, usefull when handling fixed header or sticky navigation (default: 0) |

AnchorSection

AnchorSection is our most used components, it defines the scroll position you will arrive to on navigation/reloading

<AnchorSection className="dBlock anchor" id="definitions" />

Its props are the usual HTMLElement's props (className, data-*), along with an id used for recognizing the update the current hash on scroll.

interface TProps extends React.HTMLAttributes<HTMLElement> {
  id: string;
}

Internally it creates a <b/> tag to which we scroll to on reload and detect if we scrolled past it.

<>
  <b {...attributes} />
  {...children}
</>

AnchorLink

AnchorLink is a component made to have an activeClassname if its href is the current hash

interface TProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
  children: React.ReactNode[] | React.ReactNode;
  activeClassName?: string;
}

<AnchorLink className="dTable w100 pad15" href="#definitions" activeClassName="blue">

Custom Components Examples

TODO

Testing

react-anchor-navigation can be tested with the end-to-end testing library Cypress.

To run the tests, run yarn cypress and select the test specs to run in the Cypress window.

Learn more about writing your own Cypress tests with the Cypress documentation.

Roadmap

• Finish completing the README
• Add testing