react-use-navscroll

The React hook for nav scrolling

Demo here

Install

npm install --save react-use-navscroll

Usage

import React from 'react'
import {useNavScroll} from 'react-use-navscroll'


function Example(){
  const {register, isActive} = useNavScroll();
  return <div>
    <h1 {...register('1')}>My title {isActive('1') ? '(active)' : ''}</h1>
    <h2 {...register('2')}>My subtitle {isActive('2') ? '(active)' : ''}</h2>
  </div>
}

Browser support

The hook uses the IntersectionObserver API which is available only for modern browsers. For older browsers with no support (i.e. Internet Explorer 11) it is recommended a polyfill.

Contributing

To get up and running with the development of the project you can follow these steps.

To see the component in action, useful to test it manually after some changes, open a terminal window and type:

cd example
npm start

This will start the create-react-app project and open a new browser tab with the example application in it.

At this point it is possible to perform changes to the component/library, open a new terminal in the project folder and use this command when done with changes:

npm run build

To run the test do:

npm test

Change Readme file

The readme file is autogenerated from a template located in script/readme.template: the template contains everything but the API which is generated from the Typescript source. No need to touch the API part (which will be overwritten anyway).

API

Hook

useNavScroll

useNavScroll(args : useNavScrollArgs) => useNavScrollResult

This is the main hook: use it in a react function component to track
the state of the passed ids. The function accepts an initial configuration
of type useNavScrollArgs to customize the behaviour.

Types

ChangesType

The returned object from the onChange passed function, with the current state of
added and removed element ids.

{

added: string | null,

removed: string | null

}

RegisterOptions

The options object passed to the register function.

{

parent: string,

ref: RefObject<Element>

}

The details of each property is described here:

• parent: string

Pass the string id of the parent element

• ref: RefObject<Element>

If the tracked element has already a reference, you can pass it and will be reused

useNavScrollArgs

The react-use-navscroll configuration object

{

isHorizontal: boolean,

offset: number,

root: Element,

onChange: (changes : ChangesType) => void

}

The details of each property is described here:

• isHorizontal: boolean

Declare if the detection should work vertically or horizontally. By default false (vertical)

• offset: number

Moves the detection line by the amount of this offset, expressed in percentage. By default the value is 50 (center).

• root: Element

Pass an element as root to track a specific container, smaller than a viewport. Default is window (the whole viewport).

• onChange: (changes : ChangesType) => void

Function called every time an element becomes active.
The changes object returned contains the "added" and "removed" id.

useNavScrollResult

The object returned by the hook.

{

activeIds: string[],

getActiveRef: () => null | RefObject<Element>,

isActive: (id : string) => boolean,

register: (id : string, options ?: RegisterOptions) => RegisteredAttributes<T extends Element>,

unregister: (idToUnregister : string) => void

}

The details of each property is described here:

• activeIds: string[]

A list of active ids (the full hierarchy).

• getActiveRef: () => null | RefObject<Element>

A function to retrieve the reference of the current active element (only the last element, not the elements hierarchy).

• isActive: (id : string) => boolean

A convenience function to quickly check the active state for the given id

• register: (id : string, options ?: RegisterOptions) => RegisteredAttributes<T extends Element>

The function used to register the component into the tracking system.
It returns the id already passed and the reference object.
Note that only the reference value will be null in a SSR context.

• unregister: (idToUnregister : string) => void

Removes the given id from the tracking system.

Acknowledgements

I would like to acknowledge few articles and libraries used as inspiration for this one:

• This article for the detection technique used in this library
• The React Hook Form for the inspiration about the register pattern used in this library.
• The RomaJS slack channel for preliminary the useful discussion which led to the build of this library

License

MIT © dej611