index.md

Scroll to anchor links with client-side routes e.g. with history's listen, React Router's onUpdate, or Gatsby's onRouteChange. Register a listener to call this and when window.location.hash isn't empty, it'll scrollIntoView first matching element by id or name per spec.

Originally based on: remix-run/react-router#394 (comment).

Used By

• Formidable Labs Spectacle Docs
• Formidable Labs Victory Docs
• Formidable Labs Renature Docs
• Full Stack Open 2019
• Kyma
• LessWrong

Install

npm install --save anchorate

Use

history

import { anchorate } from 'anchorate'
import { createHistory } from 'history'
 
const history = createHistory()

history.listen(() => {
  anchorate()
})

React Router

import { anchorate } from 'anchorate'
import { render } from 'react-dom'
import { Router, browserHistory } from 'react-router'

function onUpdate () {
  anchorate()
}

// ...

render((
  <Router
    onUpdate={onUpdate}
    history={browserHistory}
  />
), document.getElementById('app'))

Gatsby

In gatsby-browser.js:

const { anchorate } = require('anchorate')

exports.onRouteUpdate = () => {
  anchorate()
}

Customize the scrolling behavior

You can provide your own scrolling behavior by passing in a scroller function in an options object. It is expected that you return true if the scroll was successful.

anchorate({ 
  scroller: function (element) {
    if (!element) return false
    element.scrollIntoView({ behavior: 'smooth' })
    return true
  }
})

Getting results

You can provide a completion callback function in the options object to be informed when the operation has complete and if there were any errors. An error will be returned if the element referred to in the hash was not found.

anchorate({ 
  callback: function (error) {
    if (error) {
      // Do something
    }
  }
})