Adhesive Core

A modern, performant, lightweight, dependency free, cross platform solution for flexible sticky positioned elements.

🛠️ Installation

# ✨ Auto-detect
npx nypm install @adhesivejs/core

# npm
npm install @adhesivejs/core

# yarn
yarn add @adhesivejs/core

# pnpm
pnpm install @adhesivejs/core

# bun
bun install @adhesivejs/core

# deno
deno install @adhesivejs/core

🎨 Usage

Basic Example

import { Adhesive } from "@adhesivejs/core";

Adhesive.create({ targetEl: "#target-element" });

Advanced Example

import { Adhesive } from "@adhesivejs/core";

// Advanced configuration with all options
const adhesive = new Adhesive({
  targetEl: document.querySelector(".sidebar"),
  boundingEl: ".main-content",
  position: "bottom",
  offset: 20,
  zIndex: 999,
  outerClassName: "custom-outer",
  innerClassName: "custom-inner",
  initialClassName: "custom-initial",
  fixedClassName: "custom-fixed",
  relativeClassName: "custom-relative",
  onStatusChange: (status) => console.log("Status changed:", status),
});

// Initialize the sticky behavior
adhesive.init();

// Listen to state changes
const state = adhesive.getState();
console.log("Current status:", state.status);

// Update options dynamically (partial update)
adhesive.updateOptions({
  offset: 50,
  position: "top",
  // Other options remain unchanged
});

// Replace options (full update with fallback to defaults)
adhesive.replaceOptions({
  offset: 50,
  position: "top",
  // All other options reset to their default values
});

// Enable/disable
adhesive.disable();
adhesive.enable();

// Clean up when done
adhesive.cleanup();

API Reference

Constructor Options

| Option | Type | Default | Description | | ------------------- | ---------------------------------- | ---------------------------- | ------------------------------------------ | | targetEl | HTMLElement \| string | Required | Element to make sticky or CSS selector | | boundingEl | HTMLElement \| string \| null | document.body | Container that defines sticky boundaries | | position | 'top' \| 'bottom' | 'top' | Where the element should stick | | offset | number | 0 | Offset in pixels from the position | | zIndex | number | string | var(--adhesive-z-index, 1) | Z-index for the fixed element | | enabled | boolean | true | Whether to enable sticky behavior | | outerClassName | string | 'adhesive__outer' | Class for the outer wrapper | | innerClassName | string | 'adhesive__inner' | Class for the inner wrapper | | initialClassName | string | 'adhesive--initial' | Class when element is in its initial state | | fixedClassName | string | 'adhesive--fixed' | Class when element is sticky | | relativeClassName | string | 'adhesive--relative' | Class when element reaches its boundary | | onStatusChange | (status: AdhesiveStatus) => void | undefined | Callback fired whenever the status updates |

Methods

• init() - Initialize sticky behavior
• enable() - Enable sticky behavior
• disable() - Disable sticky behavior
• updateOptions(options) - Update configuration options (partial update)
• replaceOptions(options) - Replace configuration options (full update)
• getState() - Get current state
• refresh() - Update dimensions and positions
• cleanup() - Remove all listeners and clean up

Static Methods

• Adhesive.create(options) - Create and initialize in one call

Markup & styling hooks

Adhesive wraps your target element in two divs. The outer wrapper receives a data attribute reflecting the current status so you can style with attribute selectors or utilities:

• data-adhesive-status="initial"
• data-adhesive-status="fixed"
• data-adhesive-status="relative"

Example CSS:

[data-adhesive-status="fixed"] {
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}
[data-adhesive-status="relative"] {
  opacity: 0.95;
}

Tailwind/UnoCSS example (using arbitrary variants):

<div id="sticky-element">
  <span
    class="[[data-adhesive-status=initial]_&]:text-red-500 [[data-adhesive-status=fixed]_&]:text-green-500 [[data-adhesive-status=relative]_&]:text-blue-500"
  >
    Dynamic styling based on status
  </span>
</div>