Affix
affixPins content after a scroll threshold while preserving its layout position.
Usage
Ceiling
offsetTop Set the distance px from the top of the container when it is adsorbed and fixed. The original position is supported by equal-height placeholder elements to prevent the layout from jumping.
Scroll down ↓ Make the action bar ceiling
Content line 1
Content line 2
Content line 3
Content line 4
Content line 5
Content line 6
Content line 7
Content line 8
Content line 9
Content line 10
Content line 11
Content line 12
Content line 13
Content line 14
Content line 15
Content line 16
Content line 17
Content line 18
<Affix offsetTop={8}>
<div className="rounded border bg-primary px-4 py-2 text-bg">Operation bar</div>
</Affix>Bottom suction
Use offsetBottom instead, nailing content to the bottom when scrolling past the container bottom threshold (only takes effect when offsetTop is not given).
Scroll up ↑ Let the action bar suck to the bottom
Content line 1
Content line 2
Content line 3
Content line 4
Content line 5
Content line 6
Content line 7
Content line 8
Content line 9
Content line 10
Content line 11
Content line 12
Content line 13
Content line 14
Content line 15
Content line 16
Content line 17
Content line 18
<Affix offsetBottom={8}>
<div className="rounded border bg-primary px-4 py-2 text-bg">Operation bar</div>
</Affix>Add shadow when adsorbing
affixedClassName adds a class name to the adsorption state, which is often used to raise shadows during adsorption; onChange can synchronize the adsorption state.
Scroll down ↓ Make the action bar ceiling
Content line 1
Content line 2
Content line 3
Content line 4
Content line 5
Content line 6
Content line 7
Content line 8
Content line 9
Content line 10
Content line 11
Content line 12
Content line 13
Content line 14
Content line 15
Content line 16
Content line 17
Content line 18
<Affix offsetTop={8} affixedClassName="shadow-lg" onChange={setAffixed}>
<div className="rounded border bg-primary px-4 py-2 text-bg">Operation bar</div>
</Affix>When to use
Use Affix when content such as an action bar, table of contents, or form submit row should switch to position:fixed after crossing a scroll threshold. An equal-height placeholder preserves layout at its original position. Use Anchor to jump between page sections or BackTop for a single return-to-top action; Affix pins arbitrary children at a viewport edge.
Import
import { Affix } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| offsetTop | number | 0 | Distance in pixels from the container top at which the content becomes fixed. |
| offsetBottom | number | — | Distance from the container bottom. Used only when offsetTop is absent; top takes precedence when both are provided. |
| target | HTMLElement | Window | null | (() => HTMLElement | Window | null) | window | Scroll event target, provided directly or through a getter. |
| affixedClassName | string | — | Class name added while fixed, such as shadow-lg. |
Also inheritsHTMLAttributes<HTMLDivElement>exceptchildrenandonChange.
Events
| Event | Type | Description |
|---|---|---|
| onChange | (affixed: boolean) => void | Called when the affixed state changes. |
Slots
| Slot | Type | Description |
|---|---|---|
| children* | ReactNode | Content to pin. |
Example
const ref = useRef<HTMLDivElement>(null);
<div ref={ref} className="h-64 overflow-auto">
<Affix target={() => ref.current} offsetTop={8} affixedClassName="shadow-lg">
<div className="rounded bg-primary px-4 py-2 text-bg">Action bar</div>
</Affix>
{/* Long content */}
</div>Usage guidelines
- When an intermediate element such as
<main class="overflow-y-auto">is the actual scroller, pass it throughtarget. The implementation captures window scroll events to cover intermediate containers; without the correct target, the fixed bar can retain stale viewport coordinates and drift outside its container. See [[affix-fixed-must-capture-scroll-for-intermediate-container]]. - Documentation previews and other layouts where window does not scroll must target their real scroll frame or Affix never activates.
Related
Tabs · Breadcrumb · Pagination · Anchor · BackTop · Stepper
Playground
Scroll down ↓ Make the action bar ceiling
Content line 1
Content line 2
Content line 3
Content line 4
Content line 5
Content line 6
Content line 7
Content line 8
Content line 9
Content line 10
Content line 11
Content line 12
Content line 13
Content line 14
Content line 15
Content line 16
Content line 17
Content line 18
<Affix offsetTop={8}>
<div>Operation Bar</div>
</Affix>