Adhesive React

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

🛠️ Installation

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

# npm
npm install @adhesivejs/react

# yarn
yarn add @adhesivejs/react

# pnpm
pnpm install @adhesivejs/react

# bun
bun install @adhesivejs/react

# deno
deno install @adhesivejs/react

🎨 Usage

Basic Example

import { AdhesiveContainer } from "@adhesivejs/react";

export function Component() {
  return (
    <div>
      <AdhesiveContainer position="top">
        <header>This header will stick to the top</header>
      </AdhesiveContainer>

      <main>
        <p>Your main content here...</p>
      </main>
    </div>
  );
}

Advanced Example with useAdhesive Hook

import { useAdhesive, type AdhesivePosition } from "@adhesivejs/react";
import { useRef, useState } from "react";

export function Component() {
  const targetRef = useRef<HTMLDivElement>(null);
  const boundingRef = useRef<HTMLDivElement>(null);
  const [enabled, setEnabled] = useState(true);
  const [position, setPosition] = useState<AdhesivePosition>("top");

  const { status } = useAdhesive(targetRef, {
    boundingRef,
    position,
    offset: 20,
    enabled,
    zIndex: 999,
    initialClassName: "custom-initial",
    fixedClassName: "custom-fixed",
    relativeClassName: "custom-relative",
  });

  return (
    <div ref={boundingRef} style={{ height: "200vh" }}>
      <button onClick={() => setEnabled(!enabled)}>
        {enabled ? "Disable" : "Enable"} Sticky
      </button>

      <button
        onClick={() => setPosition(position === "top" ? "bottom" : "top")}
      >
        Switch to {position === "top" ? "bottom" : "top"}
      </button>

      <div ref={targetRef} className="sticky-element">
        <h2>Dynamic Sticky Element</h2>
        <p>
          Position: {position} | Enabled: {enabled ? "Yes" : "No"} | Status:{" "}
          {status}
        </p>
      </div>

      <div
        style={{
          height: "150vh",
          background: "linear-gradient(to bottom, #f0f0f0, #ffffff)",
        }}
      >
        <p>Scroll to see the sticky behavior in action!</p>
      </div>
    </div>
  );
}

API Reference

AdhesiveContainer Component

A simple wrapper component that automatically applies sticky positioning to its children.

Props:

• All props from UseAdhesiveOptions (see below)
• Standard div props (className, style, etc.)

<AdhesiveContainer position="bottom" offset={30} className="custom-class">
  Content to make sticky
</AdhesiveContainer>

useAdhesive Hook

For more control over the sticky behavior.

Parameters:

• target: React ref object for the element that should become sticky
• options: Configuration options (optional)

UseAdhesiveOptions:

| Option | Type | Default | Description | | ------------------- | ---------------------------------------------- | ---------------------------- | --------------------------------------------------------------- | | boundingRef | React.RefObject | HTMLElement | string | document.body | The element that defines the sticky boundaries | | boundingEl | HTMLElement | string | document.body | Alternative way to specify bounding element (for compatibility) | | 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 |