react-anchor-navigation

Description

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

📖 table of content

• Installation
• How to use
• How to test
• How to contribute
• List of our other package
• Join us
• License

🚀 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

🖥️ How to use

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">

⏳ How to test

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.

🤝 How to contribute

• fork the project

• install dependencies (yarn)

• create a branch from main/master like that

  $ contribution/fix/your-github-identity

  OR

  $ contribution/improvment/your-github-identity

• push several (if needed) clear commits

• add tests following the way of the other ones have been wrote

• make sure that all test runs

• push your code

📦 List of our other package

• is-emoji-supported
• frenchkiss
• wowza-webrtc-player
• react-rich-mentions
• react-anchor-navigation

⛵ Join us

May you want to share more than a pull request check our jobs opportunity

License

Copyright (c) 2023 Koala-Interactive

This project is MIT licensed.