bangrrrt / react-scrollchor

A React component for scroll to `#hash` links with smooth animations

react-scrollchor (React Scrollchor)

A React component for scroll to #hash links with smooth animations. Scrollchor is a mix of Scroll and Anchor, a joke name for a useful component.

See it in action:

• demo video
• example page and source code

hash is the id of a HTML tag on current page.

Installation

npm

npm install react-scrollchor --save

Dependencies

• User should provide their own React package

Usage

import Scrollchor from 'react-scrollchor';

export default (props) => (
  <Page>

    <Navbar brand={brand} className="navbar-fixed-top">
      <NavItem><Scrollchor to="" className="nav-link">Home</Scrollchor></NavItem>
      <NavItem><Scrollchor to="#sample-code" className="nav-link">Sample</Scrollchor></NavItem>
      <NavItem><Scrollchor to="#features" className="nav-link">Features</Scrollchor></NavItem>
      <NavItem><Scrollchor to="footer" className="nav-link">SignUp</Scrollchor></NavItem>
    </Navbar>


  <Section id="sample-code">

  </Section>

  <div id="features">

  </div>

  <footer id="footer">

  </footer>

</Page>

Prop types

  propTypes: {

    /**
     * id attribute of the target DOM node
     * - `#` can be omitted
     * - let it blank, `to = ''`, for scroll to page top
     * - this prop is required
     */
    to: PropTypes.string.isRequired,

    /**
     * id attribute of the scrollable DOM node
     * - `#` can be omitted
     * - uses the root element of the document if omitted
     */
    target: PropTypes.string,

    /**
     * scroll smooth animation can be customized
     * Accepted options, Ex: (default)
     *  { offset: 0, duration: 400, easing: easeOutQuad }
     */
    animate: PropTypes.object,

    /**
     * callback function triggered before scroll to #hash
     * @param1 Received click event
     */
    beforeAnimate: PropTypes.func,

    /**
     * callback function triggered after scroll to #hash
     * @param1 Received click event
     */
    afterAnimate: PropTypes.func

    /**
     * enable/disable update browser history with scroll behaviours
     * Default to `false`
     */
    disableHistory: PropTypes.bool
}

Reactive props

Update props will re-render Scrollchor element

Example: updating "to" prop

Custom animations

Animation behavior can be customized:

<Scrollchor to="#aboutus" animate={{offset: 20, duration: 600}} className="nav-link">Home</Scrollchor>

default animation settings

{ offset: 0, duration: 400, easing: easeOutQuad }

This setting is equivalent to default jQuery.animate easing: swing

more Easing functions

• jQuery easings
• Robert Penner's Easing Functions
• Javascript source code

before and after Animate callbacks

Use these callbacks to trigger behaviors like: update state, load async stuff, etc.

<Scrollchor to="#aboutus" afterAnimate={() => updateState(this)}>Home</Scrollchor>

Simulate click API

Scrollchor includes a dedicate API to do animate scroll programmatically that works like normal click events using simulateClick().

Example: using simulateClick

When used programmatically, some use-cases don't need anchor tags. On these cases use childless Scrollchor.

Childless Scrollchor

This component will render null and the user is reponsible for storing the component reference, Ex: childless

<Scrollchor ref={ref => (this._back = ref)} to="_back" />

Example: calling simulateClick() on childless ref

_afterAnimate = () => {
  this.setState({ to: this._iterator.next().value });
    setTimeout(() => this._back.simulateClick(), 1000);
};

Scrollable ancestor container

Scrollchor works within any scrollable parent container. The root element of the document will be choose if none is specified.

Hosted example show how to use a different container using prop target.

• Click Within scrollable container checkbox: hosted example(full example below)

Full Example

react-scrollchor--example

Credits

author

• bySabi Files <> @bySabi

maintainers

• xehpuk <> @xehpuk

contributors

• Jean Chung <> @jeanchung
• Chua Kang Ming <> @kambing86
• Benjamin MICHEL <> @SBRK

Contributing

• Documentation improvement
• Feel free to send any PR

License

ISC