useIsStuck
Tells you whether a position: sticky element is currently stuck, so you can
style it differently only while it is pinned, for example with a shadow under a
sticky header. CSS has no selector for this state, and a scroll listener would
run on every scroll event. useIsStuck uses an IntersectionObserver on a
hidden marker next to your element, so your component only re-renders when the
state flips.
It differs from useIntersectionObserver,
which reports whether an element is visible. A sticky element stays visible
while it is stuck, so visibility cannot tell you this.
When to use it
- A shadow or border under a sticky header or toolbar once content scrolls beneath it.
- A bottom action bar that floats over a long form and looks flat at the end.
- Sticky table headers, side navigation and section titles that change style while pinned.
- Showing a compact version of a header while it is stuck.
Demo
Scroll each box. The first shows a header gaining a shadow while it is stuck to
the top of a scroll container. The second uses side: "bottom" for an action
bar. The third stacks two bars and uses offset for the one that sticks below
the other.
Signature
type UseIsStuckSide = "top" | "bottom" | "left" | "right";
interface UseIsStuckOptions {
side?: UseIsStuckSide;
offset?: number;
root?: Element | Document | null;
enabled?: boolean;
}
interface UseIsStuckResult<T extends Element> {
ref: (element: T | null) => void;
isStuck: boolean;
}
function useIsStuck<T extends Element = HTMLElement>(
options?: UseIsStuckOptions
): UseIsStuckResult<T>;
| Option | Type | Description |
|---|---|---|
side | "top" | "bottom" | "left" | "right" | The edge the element sticks to, matching its CSS property. Defaults to "top". |
offset | number | The sticky distance from that edge in pixels, for example 64 for top: 64px. Negative or non-finite values are treated as 0. Defaults to 0. |
root | Element | Document | null | The scroll container the element sticks inside. Defaults to the browser viewport. |
enabled | boolean | Set to false to stop observing. isStuck is false while disabled. Defaults to true. |
Returns: an object with:
ref: a callback ref to attach to the sticky element.isStuck:truewhile the element is pinned at its sticky edge, otherwisefalse.
Usage notes
- A callback ref. It works for elements that mount later, render
conditionally or are swapped for another one. The returned function is stable
across renders. To combine it with another ref, call both from a function
ref:
ref={(el) => { stuckRef(el); myRef.current = el; }}. - Match
sideandoffsetto your CSS.sideis the property you set (top,bottom,left,right) andoffsetis its value in pixels. An element withposition: sticky; top: 64pxneedsoffset: 64. The hook does not read your styles, so keep the two in sync, for example by using one constant for both. - Scroll containers. When the element sticks inside a scrollable element
rather than the page, pass that element as
root. Store it in state with a callback ref (ref={setRoot}), as the demos do, so the hook re-observes once it mounts. - Re-renders only on change. The state flips when the element becomes pinned or is released, not on every scroll event.
- How it works. A sticky element is always visible, so its own position
cannot tell you whether it was pushed from where it would be without
stickiness. The hook inserts a zero-size,
aria-hidden<div>(a sentinel) next to the element, where the element would sit in normal flow, and observes it. The element is stuck once that marker has scrolled past the sticky edge. The marker is removed on cleanup, and it is only added after mount, so it never causes a hydration mismatch. - The marker is a sibling. In a normal block layout it takes no space. In a
flex or grid parent it counts as one more child. A
gapmakesisStuckflip about one gap earlier than the element pins, and:nth-childselectors or explicit grid placement can notice it. Without agapthe result is exact. - Horizontal sides.
leftandrightare meant for an element in a flex row, where the marker sits right next to it. In other layouts the marker may not line up with the element, so prefertopandbottomthere. - Scrolled out by its container. When the sticky element's container ends,
the element is released and scrolls out of view past the sticky edge. It
keeps reporting
truewhile its marker is beyond that edge. - The initial value.
isStuckisfalseon the server, on the first render, and until the browser reports the element's position, right after it mounts. An element that is already stuck when it mounts, for example after a scroll restoration, switches totrueright away. - Disabling.
enabled: falsedisconnects the observer andisStuckisfalse. Turn it back on to measure again. - Server rendering and unsupported browsers. Nothing runs on the server.
Where
IntersectionObserveris unavailableisStuckstaysfalse. - Cleanup. The observer is disconnected on unmount, when the element or an
option changes, and when
enabledbecomesfalse. - Testing. jsdom does not provide
IntersectionObserver, so mock it and call its callback with an entry that hasboundingClientRectandrootBounds, wrapped inact. - Safe under React
StrictMode.
Examples
// Add a shadow to a sticky header while it is pinned to the top
const { ref, isStuck } = useIsStuck<HTMLElement>();
return (
<header
ref={ref}
style={{
position: "sticky",
top: 0,
boxShadow: isStuck ? "0 2px 8px rgba(0, 0, 0, 0.2)" : "none",
}}
>
Title
</header>
);
// A bottom action bar, and a header that sticks 64px from the top
const bar = useIsStuck<HTMLDivElement>({ side: "bottom" });
const header = useIsStuck<HTMLDivElement>({ offset: 64 });
// A sticky table header inside a scrollable container
const [scroller, setScroller] = useState<HTMLDivElement | null>(null);
const { ref, isStuck } = useIsStuck<HTMLTableRowElement>({ root: scroller });
// Build your own helper on top, which toggles a data attribute
const useStickyAttribute = <T extends HTMLElement>(
options?: UseIsStuckOptions
) => {
const { ref, isStuck } = useIsStuck<T>(options);
return { ref, "data-stuck": isStuck || undefined };
};
Hook source
View useIsStuck source
useIsStuck sourceimport { useEffect, useState } from "react";
/** The edge of the scroll area a sticky element sticks to. */
export type UseIsStuckSide = "top" | "bottom" | "left" | "right";
/** Options for {@link useIsStuck}. */
export interface UseIsStuckOptions {
/**
* The edge of the root the element sticks to, matching the CSS property you
* gave it (`top`, `bottom`, `left` or `right`). Default is `"top"`.
*/
side?: UseIsStuckSide;
/**
* The distance in pixels between the root's edge and the element while it
* is stuck, which is the value of its CSS `top` (or `bottom`, `left`,
* `right`). A negative or non-finite value is treated as `0`. Default is
* `0`.
*/
offset?: number;
/**
* The scroll container the element sticks inside. Pass a scrollable element
* when the sticky element is not stuck to the browser viewport. Passing a
* new element re-observes. Default is the browser viewport (`null`).
*/
root?: Element | Document | null;
/**
* Set to `false` to stop observing. `isStuck` is `false` while disabled, and
* observing starts again when it is `true`. Default is `true`.
*/
enabled?: boolean;
}
/** The object returned by {@link useIsStuck}. */
export interface UseIsStuckResult<T extends Element> {
/** Attach this to the `position: sticky` element, as its `ref`. */
ref: (element: T | null) => void;
/** Whether the element is currently pinned at its sticky edge. */
isStuck: boolean;
}
/**
* Builds the `rootMargin` that moves the root's `side` edge inwards by
* `offset` pixels, which is where the element pins.
*
* @param side - The edge the element sticks to.
* @param offset - The sticky distance from that edge, in pixels.
* @returns A `rootMargin` string in CSS margin syntax (top right bottom left).
*/
const getRootMargin = (side: UseIsStuckSide, offset: number) => {
const inset = `${-offset}px`;
switch (side) {
case "top":
return `${inset} 0px 0px 0px`;
case "right":
return `0px ${inset} 0px 0px`;
case "bottom":
return `0px 0px ${inset} 0px`;
case "left":
return `0px 0px 0px ${inset}`;
}
};
/**
* Creates the zero-size marker that sits where the element would be without
* `position: sticky`. It is in normal flow, so it scrolls with the content
* like the element's own slot does, but it has no size, so it takes no space.
* It is hidden from assistive technology.
*
* @returns The element to insert next to the sticky element.
*/
const createSentinel = () => {
const sentinel = document.createElement("div");
sentinel.setAttribute("aria-hidden", "true");
sentinel.style.cssText =
"display:block;width:0;height:0;margin:0;padding:0;border:0;" +
"overflow:hidden;pointer-events:none;";
return sentinel;
};
/**
* Tells whether the sentinel has moved past the root's `side` edge, which means
* the element has been pushed from its natural position and is pinned.
*
* @param entry - The latest observer entry for the sentinel.
* @param side - The edge the element sticks to.
* @returns `true` if the sentinel is beyond that edge of the root.
*/
const isPastEdge = (entry: IntersectionObserverEntry, side: UseIsStuckSide) => {
const { boundingClientRect: rect, rootBounds: bounds } = entry;
// `rootBounds` is `null` for a cross-origin root, so nothing can be told.
if (entry.isIntersecting || !bounds) return false;
switch (side) {
case "top":
return rect.top < bounds.top;
case "right":
return rect.left > bounds.right;
case "bottom":
return rect.top > bounds.bottom;
case "left":
return rect.left < bounds.left;
}
};
/**
* Tells whether a `position: sticky` element is currently stuck, so you can
* give sticky headers, toolbars and action bars a shadow, a border or a
* different background only while they are pinned.
*
* It uses an `IntersectionObserver` and no scroll listener, so it does no work
* on scroll events. CSS cannot tell you where a sticky element would be
* without sticking, so the hook inserts a hidden zero-size marker (a sentinel) next
* to the element at that natural position and watches it leave the scroll
* area. The marker has no size, so it takes no space in a normal block layout.
*
* - **Usage:** attach the returned `ref` to the element that has
* `position: sticky`. It is a callback ref, so it also works when the
* element mounts later, is rendered conditionally, or is swapped for another
* one.
* - **Sides:** `side` picks the edge (`top`, `bottom`, `left` or `right`) and
* `offset` is the sticky distance from it, for example `offset: 64` for
* `top: 64px`.
* - **Scroll containers:** pass the scrollable element as `root` when the
* element sticks inside it rather than to the page.
* - **Efficient:** it re-renders only when `isStuck` changes, not while you
* scroll.
* - **Pause:** `enabled: false` disconnects the observer and `isStuck` is
* `false` until it is turned back on.
* - **SSR-safe:** `isStuck` is `false` on the server, on the first render, and
* wherever `IntersectionObserver` is unavailable.
* - **Cleanup:** the observer is disconnected and the marker is removed on
* unmount, when the element or an option changes, and when `enabled`
* becomes `false`.
*
* Because the marker is a real child of the element's parent, a flex or grid
* parent treats it as one more item, which a `gap` or an explicit grid
* placement can notice. For `left` and `right` the element should be in a
* flex row, where the marker sits right next to it.
*
* @typeParam T - The type of the sticky element. Defaults to `HTMLElement`.
* @param options - Optional `side`, `offset`, `root` and `enabled` settings. See {@link UseIsStuckOptions | UseIsStuckOptions}.
* @returns Whether the element `isStuck`, and the `ref` to attach to it.
*
* @example
* ```tsx
* // Add a shadow to a sticky header while it is pinned to the top
* const { ref, isStuck } = useIsStuck<HTMLElement>();
*
* return (
* <header
* ref={ref}
* style={{
* position: "sticky",
* top: 0,
* boxShadow: isStuck ? "0 2px 8px rgba(0, 0, 0, 0.2)" : "none",
* }}
* >
* Title
* </header>
* );
* ```
*
* @example
* ```tsx
* // A bottom action bar, and a header that sticks 64px from the top
* const bar = useIsStuck<HTMLDivElement>({ side: "bottom" });
* const header = useIsStuck<HTMLDivElement>({ offset: 64 });
* ```
*
* @example
* ```tsx
* // A sticky table header inside a scrollable container
* const [scroller, setScroller] = useState<HTMLDivElement | null>(null);
* const { ref, isStuck } = useIsStuck<HTMLTableRowElement>({ root: scroller });
* ```
*
* For a live, editable example, see the [useIsStuck docs page](https://altalyst-solutions.github.io/hookify/hooks/use-is-stuck).
*
* @see [position: sticky](https://developer.mozilla.org/en-US/docs/Web/CSS/position#sticky)
* @see [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)
*/
export const useIsStuck = <T extends Element = HTMLElement>(
options?: UseIsStuckOptions
): UseIsStuckResult<T> => {
/** The edge the element sticks to. */
const side = options?.side ?? "top";
/** The raw sticky distance as passed, before it is validated. */
const rawOffset = options?.offset ?? 0;
/** The sticky distance in pixels. Never negative or non-finite. */
const offset = Number.isFinite(rawOffset) && rawOffset > 0 ? rawOffset : 0;
/** The scroll container used as the viewport, `null` for the browser's. */
const root = options?.root ?? null;
/** Whether observing is on. */
const enabled = options?.enabled ?? true;
/** The sticky element. Set by the returned callback ref. */
const [element, setElement] = useState<T | null>(null);
/** The latest result, with the element it was measured for. */
const [result, setResult] = useState<{ target: Element; stuck: boolean }>();
/** Ignore a result that belongs to a previous element or a paused hook. */
const isStuck =
enabled && element !== null && result?.target === element && result.stuck;
useEffect(() => {
const parent = element?.parentNode;
if (
!enabled ||
!element ||
!parent ||
typeof IntersectionObserver === "undefined"
) {
return;
}
/** The marker at the element's natural position. */
const sentinel = createSentinel();
// The marker goes after the element on the far sides and before it on the
// near ones, so it sits on the element's natural edge on `side`.
parent.insertBefore(
sentinel,
side === "top" || side === "left" ? element : element.nextSibling
);
/** The last value reported by this observer, to skip unchanged ones. */
let last: boolean | undefined;
const observer = new IntersectionObserver(
(entries) => {
const entry = entries[entries.length - 1];
if (!entry) return;
const stuck = isPastEdge(entry, side);
if (stuck === last) return;
last = stuck;
setResult({ target: element, stuck });
},
{ root, rootMargin: getRootMargin(side, offset) }
);
observer.observe(sentinel);
return () => {
observer.disconnect();
sentinel.remove();
};
}, [element, enabled, offset, root, side]);
return { ref: setElement, isStuck };
};