dynamic-sticky-sidebardynamic-sticky-sidebar
Guide
  • Vanilla JS
  • React
  • Vue
API
Demo
npm
  • English
  • فارسی
  • العربية
  • Deutsch
  • Français
  • Italiano
GitHub
Guide
  • Vanilla JS
  • React
  • Vue
API
Demo
npm
  • English
  • فارسی
  • العربية
  • Deutsch
  • Français
  • Italiano
GitHub
  • Guide

    • Introduction
    • Getting Started
    • Layout Requirements
    • Dynamic Headers
    • How It Works
    • Troubleshooting
  • Frameworks

    • Vanilla JS
    • React
    • Vue
  • Reference

    • API Reference
    • Live Demo

Introduction

dynamic-sticky-sidebar keeps a sidebar in view while the page scrolls, even when the sidebar is taller than the screen and the header above it keeps changing size.

The problem

Plain position: sticky; top: 80px works well until one of these happens:

  • The sidebar is taller than the viewport. It pins to the top and its lower part can never be reached until the end of the page.
  • The header hides and shows. Many sites slide the header (or a second nav row) away on scroll down and bring it back on scroll up. A fixed top either leaves a gap or slips under the header.
  • The header changes height. Banners close, search bars expand and headers collapse into a compact mode.

The usual fixes either listen to scroll and set transform or top on every frame, which causes jitter and lag, or need hand-tuned offsets for every header state.

What this library does

  • Two-way sticky. Scrolling down, a tall sidebar moves with the content until its bottom reaches the viewport, then sticks. Scrolling up, it moves back until its top reaches the header, then sticks. A short sidebar simply stays pinned under the header.
  • Live header tracking. You pass the header element(s) and the sidebar sits under the lowest visible header edge. It follows the header frame by frame while the header slides, collapses or resizes.
  • Native first. The browser's position: sticky handles each scroll frame. JS only changes the sticky constraints (top, bottom, a margin) when the scroll direction flips or the header moves. See How it works.

Packages

There is one npm package with three entry points:

ImportUse it for
dynamic-sticky-sidebarFramework-free core: stickySidebar()
dynamic-sticky-sidebar/reactuseStickySidebar hook and <StickySidebar> component
dynamic-sticky-sidebar/vueComposable, v-sticky-sidebar directive and plugin

React (≥ 16.8) and Vue (≥ 3.3) are optional peer dependencies. Install only what you use.

Types ship with the package and resolve for both moduleResolution: "bundler" / "node16" and the older "node" setting.

Bundle size

Measured on the published build, minified with NODE_ENV=production as your bundler would. The React and Vue entries include the core.

EntryMinifiedgzipbrotli
dynamic-sticky-sidebar3.4 kB1.8 kB1.6 kB
dynamic-sticky-sidebar/react4.6 kB2.2 kB2.0 kB
dynamic-sticky-sidebar/vue4.2 kB2.1 kB1.9 kB
CDN <script> build3.8 kB2.0 kB1.8 kB
  • No dependencies. React and Vue are only used by their own entry points.
  • Development warnings are stripped in production. The console hints from Troubleshooting are wrapped in process.env.NODE_ENV !== 'production', so Vite, webpack, Next.js and Nuxt remove them from production bundles. The development build of the core is about 0.2 kB larger (gzip).
  • Tree-shakeable. The package is marked sideEffects: false, and the React component is annotated as pure, so unused exports are dropped.

Run pnpm size in the repository to reproduce these numbers.

Browser support

Any browser with position: sticky, ResizeObserver and MutationObserver, which covers every current evergreen browser. Both the ESM/CJS builds and the CDN <script> build target ES2020.

Edit this page on GitHub
Next
Getting Started