isabella232 / react-sticky

<Sticky /> component for awesome React apps

react-sticky

The most powerful Sticky library available for React!

Demos

• Basic
• Timeline

Highlights

• Fully-nestable, allowing you to build awesome layouts with familiar syntax
• Sane defaults so you spend less time configuring
• Allows multiple Sticky elements on the page at once with compositional awareness!

Installation

npm install react-sticky

Tip: run npm build to build the compressed UMD version suitable for inclusion via CommonJS, AMD, and even good old fashioned <script> tags (available as ReactSticky).

Overview & Basic Example

It all starts with a <StickyContainer />. This is basically a plain ol' <div /> with a React-managed padding-top css attribute. As you scroll down the page, all <Sticky /> tags within will be constrained to the bounds of its closest <StickyContainer /> parent.

The elements you actually want to "stick" should be wrapped in the <Sticky /> tag. The full list of props are available below, but typical usage will look something like so:

app.jsx

import React from 'react';
import { StickyContainer, Sticky } from 'react-sticky';
...

class App extends React.Component ({
  render() {
    return (
      ...
      <StickyContainer>
        ...
        <Sticky>
          <header>
            ...
          </header>
        </Sticky>
        ...
      </StickyContainer>
      ...
    );
  },
});

When the "stickiness" becomes activated, the following inline style rules are applied to the Sticky element:

  position: fixed;
  top: 0;
  left: 0;
  width: < width is inherited from the closest StickyContainer >

Note that the calculation of the Sticky element's height does not currently take margins into account. If you have margins on this element it may result in unexpected behavior.

<StickyContainer /> Props

<StickyContainer /> passes along all props you provide to it without interference. That's right - no restrictions - go nuts!

<Sticky /> Props

stickyStyle (default: {})

In the event that you wish to override the style rules applied, simply pass in the style object as a prop:

app.jsx

<StickyContainer>
  <Sticky stickyStyle={customStyleObject}>
    <header />
  </Sticky>
</StickyContainer>

Note: You likely want to avoid messing with the following attributes in your stickyStyle: left, top, and width.

stickyClassName (default: 'sticky')

You can also specify a class name to be applied when the element becomes sticky:

app.jsx

<StickyContainer>
  ...
  <Sticky stickyClassName={customClassName}>
    <header />
  </Sticky>
  ...
</StickyContainer>

topOffset (default: 0)

Sticky state will be triggered when the top of the element is topOffset pixels from the top of the closest <StickyContainer />. Positive numbers give the impression of a lazy sticky state, whereas negative numbers are more eager in their attachment.

app.jsx

<StickyContainer>
  ...
  <Sticky topOffset={80}>
    <SomeChild />
  </Sticky>
  ...
</StickyContainer>

The above would result in an element that becomes sticky once its top is greater than or equal to 80px away from the top of the <StickyContainer />.

bottomOffset (default: 0)

Sticky state will be triggered when the bottom of the element is bottomOffset pixels from the bottom of the closest <StickyContainer />.

app.jsx

<StickyContainer>
  ...
  <Sticky bottomOffset={80}>
    <SomeChild />
  </Sticky>
  ...
</StickyContainer>

className (default: '')

You can specify a class name that would be applied to the resulting element:

app.jsx

<StickyContainer>
  ...
  <Sticky className={className}>
    <header />
  </Sticky>
  ...
</StickyContainer>

style (default: {})

You can also specify a style object that would be applied to the resulting element:

app.jsx

<StickyContainer>
  ...
  <Sticky style={{background: 'red'}}>
    <header />
  </Sticky>
</StickyContainer>

Note: In the event that stickyStyle rules conflict with style rules, stickyStyle rules take precedence ONLY while sticky state is active.

onStickyStateChange (default: function() {})

Use the onStickyStateChange prop to fire a callback function when the sticky state changes:

app.jsx

<StickyContainer>
  ...
  <Sticky onStickyStateChange={this.handleStickyStateChange}>
    <header />
  </Sticky
  ...
</StickyContainer>

isActive (default: true)

Use the isActive prop to manually turn sticky on or off:

app.jsx

<StickyContainer>
  ...
  <Sticky isActive={false}>
    <header />
  </Sticky
  ...
</StickyContainer>

License

MIT