Sidebarius

Sidebarius is a lightweight, dependency-free JavaScript tool for creating a "sticky" sidebar that adapts to scroll movements. This allows for dynamic interfaces with elements that stay in view as the user scrolls the page.

Demo 👈

Table of Contents

• Installation
• Usage
  • Vanilla JS
  • React Typescript
• API
• Limitations
• Development
  • Commit Message Guidelines
• Links
• Copyright and license

Installation

Install the package via npm:

npm install sidebarius

Usage

Vanilla JS

<main>
  <aside id="container">
    <div id="container_inner"><!-- Sidebar content --></div>
  </aside>
  <section><!-- Section content --></section>
</main>

<!-- Import globally, or use ES Modules as shown below -->
<!-- <script src="./sidebarius.iife.min.js"></script> -->

<script type="module">
  import Sidebarius from './sidebarius.esm.min.js'; // Or use the global import (see commented line above)

  const sidebarius = new Sidebarius(
    document.getElementById('container'),
    document.getElementById('container_inner'),
    16, // spaceBottom (optional, default is 0)
    16, // spaceTop (optional, default is 0)
    callback, // optional callback
  );

  sidebarius.start();

  function callback(state, direction, strategy) {
    console.log('STATE: ' + ['None', 'ContainerBottom', 'ColliderTop', 'ColliderBottom', 'TranslateY', 'Rest'][state]);
    console.log('DIRECTION: ' + ['None', 'Down', 'Up'][direction]);
    console.log('STRATEGY: ' + ['None', 'Both', 'Top'][strategy]);
  }
</script>

Latest release

React Typescript

import React, { useRef, useEffect, FC, HTMLAttributes, CSSProperties } from 'react';
import Sidebarius from 'sidebarius';

type SidebarContainerProps = Omit<HTMLAttributes<HTMLElement>, 'style'> & {
  style?: Omit<CSSProperties, 'padding'>;
};

type SidebarContainerInnerProps = Omit<HTMLAttributes<HTMLDivElement>, 'style'> & {
  style?: Omit<CSSProperties, 'margin'>;
};

interface SidebarProps {
  container?: SidebarContainerProps;
  containerInner?: SidebarContainerInnerProps;
}

const Sidebar: FC<SidebarProps> = ({ container = {}, containerInner = {}, children }) => {
  const containerRef = useRef<HTMLElement | null>(null);
  const containerInnerRef = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!containerRef.current || !containerInnerRef.current) return;

    const sidebarius = new Sidebarius(
      containerRef.current,
      containerInnerRef.current,
      16, // spaceBottom
      16, // spaceTop
    );

    sidebarius.start();

    return () => {
      sidebarius.stop();
    };
  }, []);

  return (
    <aside ref={containerRef} {...container}>
      <div ref={containerInnerRef} {...containerInner}>
        {children}
      </div>
    </aside>
  );
};

export default Sidebar;

API

| Method | Description | | ---------------------------------- | ----------------------------------------------------------- | | start() | Starts the sticky scrolling behavior. | | stop() | Stops the sticky scrolling behavior. | | setSpaces(bottomSpace, spaceTop) | Sets the distance to the collider and triggers a re-render. |

Constructor Parameters

constructor(
  container: HTMLElement,
  containerInner: HTMLElement,
  spaceBottom: number = 0,
  spaceTop: number = 0,
  callback: Callback = () => {}
);

| Parameter | Type | Description | | ---------------- | ----------- | ----------------------------------------------------------------------------------- | | container | HTMLElement | The parent element (Container) that holds the sticky element. | | containerInner | HTMLElement | The element endowed with stickiness and scrolling abilities relative to its parent. | | spaceBottom | number | The space between the bottom of the viewport and the visible area. Default is 0. | | spaceTop | number | The space between the top of the viewport and the visible area. Default is 0. | | callback | Callback | A function called before changes to the ContainerInner occur. See Callback |

Callback

type Callback = (state: State, direction: Direction, strategy: Strategy) => void;

See also: State, Direction, Strategy

State

Defines the positioning states of the ContainerInner.

| Value | Description | | ----- | -------------------------------------------------------------------------------------------------- | | 0 | None: Default behavior of ContainerInner. | | 1 | ContainerBottom: ContainerInner is affixed to the bottom of the Container. | | 2 | ColliderTop: ContainerInner is fixed at the top of the viewport area, including SpaceTop. | | 3 | ColliderBottom: ContainerInner is fixed at the bottom of the viewport area, including SpaceBottom. | | 4 | TranslateY: ContainerInner is offset along the Y-axis relative to the Container. | | 5 | Rest: Rendering is paused until the state changes. |

Direction

Defines the direction of the viewport.

| Value | Description | | ----- | -------------------------------------- | | 0 | None: No movement in the viewport. | | 1 | Down: The viewport is moving downward. | | 2 | Up: The viewport is moving upward. |

Strategy

Defines the sticky behavior strategy.

| Value | Description | | ----- | ------------------------------------------------------------- | | 0 | None: No sticky behavior is applied. | | 1 | Both: Sticky behavior is applied on both edges of the Y-axis. | | 2 | Top: Sticky behavior is applied only at the top edge. |

Limitations

1. Container cannot use the CSS property padding (must be 0).
2. ContainerInner cannot use the CSS property margin (must be 0).

Concept

Viewport concepts | Viewport | Collider

Strategy

Development

Commit Message Guidelines

• feat - new feature
• fix - bug fix
• docs - documentation
• style - formatting, whitespace, no code logic changes
• refactor - code refactoring
• test - adding/changing tests
• chore - minor tasks, build process, configuration

Examples:

git commit -m "feat: add setSpaces to set top and bottom collider spaces"
# Or
git commit -m "docs: add API usage examples"

Links

• DOM
• HTMLElement
• dimensions of elements
• coordinate systems
• viewport
• position
• this
• requestAnimationFrame
• resizeObserver
• addEventListener
• removeEventListener

Copyright and license

Copyright 2026 Mikhail Prugov. Code released under the MIT License.