Skip to content

Lightweight library for updating the URL/hash on page scrolling in React

License

Notifications You must be signed in to change notification settings

pvoznyuk/react-update-url-on-scroll

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

22 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

react-update-url-on-scroll

npm version

Lightweight library for updating the URL/hash on page scrolling in React.

  • Land on correct anchor when page is loaded, based on URL hash value or full url path.
  • URL updates automatically to reflect section in view.
  • Scroll smoothly to anchors when in-page URL changes.
  • Option to record history on URL/hash changes.
npm install --save react-update-url-on-scroll

Examples

Live Demo or Source

To run examples locally, npm run example, then open your browser to localhost:3210.

Usage

1. Creating a scrollable anchor

Use the ScrollableSection tag to wrap any React element(s), making it a scrollable anchor. Use the ScrollableLink to wrap a link to the corresponding section. You may also set a meta attribute if you want to update a document title and meta-tags.

import React, { Component } from 'react';
import ScrollableSection, { ScrollableLink } from 'react-update-url-on-scroll';

export default class Page extends Component {
  render() {
    return (
      <div>
        <ScrollableLink href="/section1">
          <a> Go to section 1 </a>
        </ScrollableLink>

        <ScrollableLink href="/section2">
          <a> Go to section 2 </a>
        </ScrollableLink>

        <ScrollableSection name={'section1'} meta={title: 'Section 1'} >
          <div> Hello World </div>
        </ScrollableSection>

        <ScrollableSection name={'section2'} meta={title: 'Section 2'}>
          <div> How are you world? </div>
        </ScrollableSection>
      </div>
    )
  }
}

In this case the address will be changed to /section1 and /section2.

You can also use hashes or combine path and hash updates:

<ScrollableLink href="#panel1">
  <a> Go to panel 1 </a>
</ScrollableLink>

<ScrollableLink href="#panel2">
  <a> Go to panel 2 </a>
</ScrollableLink>

<ScrollableSection hash={'panel1'}>
  <div> Panel 1 </div>
</ScrollableSection>

<ScrollableSection hash={'panel2'}>
  <div> Panel 2 </div>
</ScrollableSection>
<ScrollableLink href="/section1#surprise">
  <a> Go to section 1, section #surprise</a>
</ScrollableLink>

<ScrollableLink href="/section1#nothing">
  <a> Go to section 1, section #nothing </a>
</ScrollableLink>

<ScrollableSection name={'section1'} hash={'surprise'}>
  <div> Surprise </div>
</ScrollableSection>

<ScrollableSection name={'section1'} hash={'nothing'}>
  <div> Nothing </div>
</ScrollableSection>

You can also use exact prop if you want ot replace whole path with the given name/anchor.

<ScrollableSection name={'section1'} exact>
  <div> Content </div>
</ScrollableSection>

2. Configure

Access configureAnchors to customize scrolling and anchors.

Offset all scrollable anchors by a fixed amount
import { configureAnchors } from 'react-update-url-on-scroll'

// Offset all anchors by -60 to account for a fixed header
// and scroll more quickly than the default 400ms
configureAnchors({offset: 60})
Options:
option default description
affectHistory false Makes pushState if true and replaceState if false.
offset 0 Offset from top on scrolling to the section. Can be used if you have a sticky header.
keepLastAnchorHash false Keep last anchor hash.
debounce 100 Debouce the scroll event.
scrollDelay 0 Delay between page load and scrolling to the corresponding section.
scrollBehaviour 'smooth' Can be 'smooth', 'instant' and 'auto'.
scrollOnImagesLoad false Wait until all the images are loaded before scrolling to the section on page load. If it is a number the scrolling will be triggered in that timeout (in case images are still not loaded)
onSectionEnter null An event that is fired when user reaches to some another section. There are two attributes: onSectionEnter(newState, oldState)
meta null An object that may contain default title and meta-tags to set on page load. e.g. meta: {title: 'Hello', description: 'World'}
reloadOnGoingBack false Set true if you need the webpage to be reloaded when user press browser's back button

3. Utilities

A small toolkit of scrolling utilies for use with anchors

Jump to top of page in a way that plays nicely with scrollable anchors
import { goToTop } from 'react-update-url-on-scroll'

// scroll to top of the page
goToTop()

Issues and feature requests

Please open issues on Github. Issues are easier to address if you include context and code samples.

Contributing

Please contribute!

About

Lightweight library for updating the URL/hash on page scrolling in React

Resources

License

Stars

Watchers

Forks

Packages

No packages published