Affix (Next-Gen)

A high-performance affix component based on physics engine algorithms and native browser observers. Surpasses industry standards in both functionality and performance.

Performance Architecture (Surpassing Engine)

YhAffix employs a dual-layer observation system:

• IntersectionObserver: The engine automatically monitors the distance between the element and the trigger zone. When the element is more than 500px away from the viewport trigger point, all high-frequency calculations are automatically cut off, achieving extreme power efficiency.
• ResizeObserver: Deeply observes size changes across three parties — the placeholder, the content, and the target container — ensuring zero jitter during async content loading.

---

Basic Usage

Set the offset and enjoy instant snap-to feedback.

Basic Usage

Smart Bottom Affix

In position="bottom" mode, the component automatically detects the viewport bottom.

Scroll to see the 100px offset bottom affix

Bottom Affix

Teleport Positioning

Core Breakthrough: For the issue where traditional fixed positioning fails inside parent containers with transform, filter, or perspective properties, YhAffix supports the teleported prop. It teleports the rendered node to body and maintains perfect visual alignment through coordinate projection algorithms.

This container has a CSS transform (scale: 0.9). Normal affix would misalign, but this component handles it perfectly via Teleport.

Teleport

Scoped Slot

Supports real-time access to the fixed state via scoped slots, enabling more complex UI interaction logic.

Scoped Slot

Dynamic Disable

Use the disabled prop to toggle the state, suitable for permission control or complex dynamic interaction scenarios.

Dynamic Disable

Use in Nuxt

YhAffix fully supports Nuxt 3/4 SSR rendering. Since affixing depends on browser window coordinates, the component has already handled client-side activation logic internally, so you can use it with confidence.

Best Practice: In Nuxt projects, pages are usually nested within NuxtLayout or various levels of complex animation components. It is recommended to enable the teleported prop, which ensures the affix element is hoisted to the root node in the DOM tree, avoiding any intermediate-level style interference.

In Nuxt environments, enabling teleported ensures the most robust positioning behavior.

Nuxt SSR Support

API

Props

Prop	Description	Type	Default
offset	Offset distance to trigger fixing	number	0
position	Affix position	'top' | 'bottom'	'top'
target	Target container selector. Affixing stops outside this container	string	—
z-index	Z-index when fixed	number	100
teleported	Whether to teleport to a specified node for rendering, solving parent transform positioning issues	boolean	false
append-to	Target container node for teleport, used with teleported	string | HTMLElement	'body'
disabled	Whether to disable the component	boolean	false
affix-style	Extra styles passed to the fixed container	CSSProperties	{}

Events

Event Name	Description	Parameters
change	Triggered when the fixed state changes	(fixed: boolean)
scroll	Triggered in real-time while scrolling	(payload: { scrollTop: number, fixed: boolean })

Slots

Slot Name	Description	Scope Parameters
default	Content slot to be fixed	{ fixed: boolean }

Expose

Name	Description	Type
update	Manually trigger position calculation and state update	() => void
fixed	Whether currently in the fixed state	Ref<boolean>
scrollTop	Current vertical scroll distance of the scroll container	Ref<number>

Theme Variables (CSS Variables)

All color variables are integrated with the global theme system, automatically supporting dark mode:

Variable	Default	Description
--yh-affix-z-index	100	Default z-index in fixed state
--yh-affix-bg-color	var(--yh-bg-color-overlay)	Affix content background color
--yh-affix-shadow	var(--yh-shadow-md)	Shadow effect in fixed state
--yh-affix-transition-duration	var(--yh-transition-duration)	Animation duration when entering fixed state
--yh-affix-transition-timing	var(--yh-transition-timing)	Animation easing curve