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

API Reference

stickySidebar(target, options?)

function stickySidebar(target: HTMLElement | string, options?: StickySidebarOptions): StickySidebar;
ParameterTypeDescription
targetHTMLElement | stringThe sidebar element, or a selector for it. Throws [dynamic-sticky-sidebar] sidebar element not found if nothing matches.
optionsStickySidebarOptionsSee Options. All optional.

Options

type Px = number | (() => number);
type HeaderInput = string | Element | ArrayLike<Element> | null | undefined;

interface StickySidebarOptions {
    header?: HeaderInput;
    offsetTop?: Px;
    offsetBottom?: Px;
    gap?: number;
    media?: string;
    scroller?: Element | string | null;
    subscribe?: (update: () => void) => void | (() => void);
}

header

  • Type: string | Element | ArrayLike<Element> | null
  • Default: none

Sticky or fixed header element(s). A selector uses all matching elements. The sidebar pins under the lowest visible bottom edge among them and follows them live while they slide, collapse or resize. See Dynamic headers.

offsetTop

  • Type: number | () => number
  • Default: 0

Extra space between the header (or the viewport top, without a header) and the sidebar. A function is called on every recalculation.

offsetBottom

  • Type: number | () => number
  • Default: 0

Extra space between the sidebar and the viewport bottom when the sidebar is bottom-pinned.

gap

  • Type: number
  • Default: 16

Spacing in px applied on both edges, on top of offsetTop / offsetBottom.

media

  • Type: string
  • Default: always active

A media query. The instance only runs while it matches, e.g. '(min-width: 768px)'. When it stops matching, listeners are removed and inline styles restored.

scroller

  • Type: Element | string | null
  • Default: the window

The scrolling element, when the sidebar lives in a scrollable container instead of the page. All positions are measured against the scroller's visible area.

subscribe

  • Type: (update: () => void) => void | (() => void)
  • Default: none

Connects an external source that moves the header (a store, an event bus…). Call update whenever it changes and return an unsubscribe function. It is called when the instance starts and unsubscribed when it stops.

subscribe: (update) => store.subscribe(update)

Instance

interface StickySidebar {
    readonly element: HTMLElement;
    update(): void;
    refresh(): void;
    setOptions(options: StickySidebarOptions): void;
    destroy(): void;
}

element

The resolved sidebar element.

update()

Recalculates synchronously, then keeps following for a few frames in case something is still moving. Call it after changes the library can't observe. See When you need to help.

refresh()

Fully restarts: re-queries header selectors and scroller, re-evaluates media and re-detects the layout mode. Use it after header elements were replaced in the DOM.

setOptions(options)

Replaces all options; it does not merge.

  • Changing header, media, scroller or subscribe (compared by identity) restarts the instance.
  • Other changes (gap, offsetTop, offsetBottom) just recalculate.

destroy()

Removes every listener and observer, cancels pending frames, calls the subscribe cleanup and restores the sidebar's original inline styles.

React

import { StickySidebar, useStickySidebar } from 'dynamic-sticky-sidebar/react';
ExportSignature
useStickySidebar<T extends HTMLElement>(options?: UseStickySidebarOptions) => (node: T | null) => void
StickySidebarForwardRefExoticComponent<StickySidebarProps>
interface UseStickySidebarOptions extends Omit<StickySidebarOptions, 'header' | 'scroller'> {
    header?: HeaderInput | RefObject<Element | null>;
    scroller?: Element | string | null | RefObject<Element | null>;
}

interface StickySidebarProps extends UseStickySidebarOptions, HTMLAttributes<HTMLElement> {
    as?: ElementType; // default 'aside'
    children?: ReactNode;
}

See React.

Vue

import { useStickySidebar, vStickySidebar, StickySidebarPlugin } from 'dynamic-sticky-sidebar/vue';
ExportSignature
useStickySidebar(target: MaybeRefOrGetter<HTMLElement | ComponentPublicInstance | null>, options?: MaybeRefOrGetter<VueStickySidebarOptions>) => { update(): void; refresh(): void }
vStickySidebarDirective<HTMLElement, VueStickySidebarOptions | undefined>
StickySidebarPluginPlugin, which registers v-sticky-sidebar
interface VueStickySidebarOptions extends Omit<StickySidebarOptions, 'header' | 'scroller'> {
    header?: MaybeRefOrGetter<HeaderInput | ComponentPublicInstance>;
    scroller?: MaybeRefOrGetter<Element | string | null | undefined | ComponentPublicInstance>;
}

See Vue.

Edit this page on GitHub
Next
Live Demo