React Sticky Element

2.1.1 · maintenance · verified Sun Apr 19

react-sticky-el is a React component library designed to make elements stick to the viewport or a specified scrollable container as the user scrolls. It provides a straightforward `<Sticky />` component that can make any child element fixed to the top or bottom. The current stable version is 2.1.1, released in late 2021, and the project is generally considered to be in maintenance mode with infrequent updates. Key differentiators include its relative simplicity, support for custom scroll elements via the `scrollElement` prop, the ability to define a `boundaryElement` to limit stickiness, and flexible configuration for position re-checks. It ships with TypeScript type definitions, providing a typed developer experience.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'default')
```
cause Attempting to import the `Sticky` component in a CommonJS environment using `require('react-sticky-el')` without explicitly accessing the default export.

fix Change your import statement from `const Sticky = require('react-sticky-el');` to `const Sticky = require('react-sticky-el').default;`.
```
Warning: Prop `className` did not match. Server: "sticky" Client: ""
```
cause This hydration mismatch warning can occur in Server-Side Rendering (SSR) environments when the `stickyClassName` or `stickyStyle` are applied dynamically on the client, differing from the server-rendered output.

fix For SSR applications, ensure that the initial state of the `Sticky` component's class or style is consistent between server and client, or conditionally render the sticky behavior only on the client side after initial hydration.

Warnings

gotcha The component's internal height calculation does not account for `margin` styles applied directly to the sticky element's child, which can lead to unexpected positioning or overlap when the element becomes sticky.
Fix: Instead of using `margin-top` or `margin-bottom` on the element wrapped by `<Sticky />`, use `padding` or wrap the content in an additional `div` and apply margins to that wrapper.
gotcha Avoid overriding `left`, `top`, and `width` properties within the `stickyStyle` prop. These CSS properties are dynamically managed by `react-sticky-el` for correct positioning and width adjustment.
Fix: For custom styling, use `stickyClassName` to apply CSS rules via a class, or use other CSS properties in `stickyStyle` while allowing the component to control `left`, `top`, and `width`.
gotcha If your DOM structure is dynamic (e.g., elements are added or removed above the sticky component), `react-sticky-el` may not automatically re-evaluate its position, leading to incorrect stickiness. Scroll events alone might not be sufficient.
Fix: Set the `positionRecheckInterval` prop to a value greater than zero (e.g., `positionRecheckInterval={100}`) to enable periodic position re-checks alongside scroll events, ensuring responsiveness to DOM mutations.
gotcha While the peer dependencies specify `React >=16.3.0`, the project's maintenance status and older internal implementations (e.g., reliance on certain lifecycle methods) might lead to compatibility issues or warnings with React 18+.
Fix: Thoroughly test `react-sticky-el` with newer React versions. If issues arise, consider alternative sticky solutions or be prepared to address deprecation warnings.

Install

npm install react-sticky-el npm
yarn add react-sticky-el yarn
pnpm add react-sticky-el pnpm

Imports

Sticky
wrong:
```
import { Sticky } from 'react-sticky-el';
```
correct:
```
import Sticky from 'react-sticky-el';
```
The primary `Sticky` component is exported as a default export.
StickyProps
```
import type { StickyProps } from 'react-sticky-el';
```
Import the component's prop types using `import type` for TypeScript. The exact prop interface name may vary, but `StickyProps` is a common convention.
Sticky (CommonJS)
wrong:
```
const Sticky = require('react-sticky-el');
```
correct:
```
const Sticky = require('react-sticky-el').default;
```
For CommonJS environments, access the default export using the `.default` property on the module object.

Quickstart

Demonstrates basic usage of the `Sticky` component, showing how a header element becomes fixed to the top of the viewport when scrolling, while preserving its space in the document flow.

import React, { Component } from 'react';
import Sticky from 'react-sticky-el';

interface AppProps {}
interface AppState {}

class App extends Component<AppProps, AppState> {
  render() {
    return (
      <div style={{ height: '200vh', paddingBottom: '50px' }}>
        <p>Scroll down to see the header stick. This is some introductory content to create scroll space.</p>
        <div style={{ height: '500px', background: '#f0f0f0', marginBottom: '20px', padding: '20px' }}>
          Content before the sticky element. This area ensures that there's enough room to scroll before the header needs to become sticky.
        </div>
        <Sticky>
          <header style={{ background: '#333', color: 'white', padding: '15px 20px', textAlign: 'center', boxShadow: '0 2px 5px rgba(0,0,0,0.2)' }}>
            <h2>This header will stick to the top!</h2>
          </header>
        </Sticky>
        <div style={{ height: '800px', background: '#e0e0e0', marginTop: '20px', padding: '20px' }}>
          Content after the sticky element. Continue scrolling to observe the sticky behavior in action.
          The `react-sticky-el` component gracefully handles making the header fixed to the viewport
          while reserving its original space in the document flow, preventing layout shifts. You can try changing the boundary element or scroll element properties for more complex scenarios.
        </div>
      </div>
    );
  }
}

export default App;

view raw JSON →