Theia Sticky Sidebar

A lightweight JavaScript (TypeScript) library that glues your website's sidebars (or any vertical column), making them permanently visible when scrolling up and down. Useful when a sidebar is too tall or too short compared to the rest of the content. Works with virtually any design and supports multiple sidebars.

Check out some examples:

• 3 columns example
• 4 columns example
• Bootstrap 4 example
• Foundation example

Install

| Package Manager | Install Command | |-----------------|---------------------------------| | NPM | npm add theia-sticky-sidebar | | Yarn | yarn add theia-sticky-sidebar | | PNPM | pnpm add theia-sticky-sidebar |

Usage

Your website's HTML structure has to be similar to this in order to work:

<div>
    <div class="content">
        <div class="theiaStickySidebar">
            ...
        </div>
    </div>
    <div class="sidebar">
        <div class="theiaStickySidebar">
            ...
        </div>
    </div>
</div>

Note that the inner theiaStickySidebar divs are optional, but highly recommended. If you don't supply them yourself, they will be created for you, but this can be problematic: ads or iframes will be moved around and may be loaded twice.

For the above example, you can use the following code:

JavaScript

<script src="dist/theia-sticky-sidebar.min.js"></script>

<script>
    document.addEventListener('DOMContentLoaded', function () {
        const tss = new TheiaStickySidebar({
            elements: '.content, .sidebar',
            additionalMarginTop: 30
        });
    });
</script>

TypeScript

import {TheiaStickySidebar} from "theia-sticky-sidebar/dist/theia-sticky-sidebar";

document.addEventListener('DOMContentLoaded', function () {
    const tss = new TheiaStickySidebar({
        elements: '.content, .sidebar',
        additionalMarginTop: 30
    });
});

React

This example uses just one sidebar.

import React, {useEffect, useRef} from "react";
import {TheiaStickySidebar} from "theia-sticky-sidebar/dist/theia-sticky-sidebar";

export const MyComponent = () => {
    const sidebarRef = useRef<HTMLDivElement>(null);
    const theiaStickySidebarRef = useRef<TheiaStickySidebar>();

    useEffect(() => {
        // Activate sticky sidebar once the component is mounted.
        theiaStickySidebarRef.current = new TheiaStickySidebar({
            elements: sidebarRef.current!,
            additionalMarginTop: 30
        });

        // Gracefully remove the sidebar once the component is unmounted.
        return () => {
            theiaStickySidebarRef.current!.unbind();
        };
    }, []);

    return <div>
        <div class="content">
            ...
        </div>
        <div class="sidebar" ref={sidebarRef}>
            <div class="theiaStickySidebar">
                ...
            </div>
        </div>
    </div>
}

Settings

| Setting | Type | Description | |------------------------------|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | elements | string \| HTMLElement \| Array<HTMLElement> | Required. Can be a simple string selector, like .my-sidebar, or .my-sidebar-1, .my-sidebar-2. Or, it can be a DOM element, like document.querySelector('.my-sidebar'). Or, it can be an array of DOM elements. | | containerSelector | string | Selector for the sidebar's container element. If not specified, it defaults to the sidebar's parent. | | additionalMarginTop | number | An additional top margin in pixels. Defaults to 0. | | additionalMarginBottom | number | An additional bottom margin in pixels. Defaults to 0. | | updateSidebarHeight | boolean | Updates the sidebar's height. Use this if the background isn't showing properly, for example. Defaults to true. | | minWidth | number | The sidebar returns to normal if its width is below this value. Useful for responsive designs. Defaults to 0. | | disableOnResponsiveLayouts | boolean | Try to detect responsive layouts automatically and disable the sticky functionality on smaller screens. More exactly, it detects when the container and the sidebar are moved one on top of the other, instead of showing up side-by-side. Defaults to true. | | defaultPosition | string | The sidebar must have a non-static position, as the inner sticky-sidebar uses position: absolute. Defaults to relative. |

Development

If you want to work on this repository:

npm install
npm run dev

WordPress

Also available as a premium WordPress plugin that comes with a user-friendly admin panel and supports a plethora of themes out-of-the-box.