Affix

A high-performance affix component that fixes content to the top or bottom of the viewport or a target container while preserving layout space.

Performance Architecture

YhAffix employs a dual-layer observation system:

• IntersectionObserver: Monitors distance from the trigger zone. When the element is far away from the viewport, high-frequency recalculation is skipped to reduce overhead.
• ResizeObserver: Observes the placeholder, content, and target container so size changes can update the fixed position without visible jitter.

---

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

YhAffix supports themeOverrides. The component stylesheet directly consumes the following affix-specific CSS variables:

Variable	Default	Description
--yh-affix-z-index	var(--yh-z-index-fixed)	Z-index token used in the fixed state
--yh-affix-shadow	var(--yh-shadow-md)	Shadow applied while affixed
--yh-affix-transition-duration	var(--yh-duration-base)	Transition duration for fixed-state updates
--yh-affix-transition-timing	cubic-bezier(0.4, 0, 0.2, 1)	Transition timing function

Type Exports

Name	Description
YhAffixProps	Props type for YhAffix
YhAffixEmits	Emits type for YhAffix
YhAffixSlots	Slots type for YhAffix
YhAffixExpose	Expose type for YhAffix
YhAffixInstance	Public instance type for YhAffix