Waterfall

A high-performance Masonry layout component. Its core algorithm uses shortest column balancing and supports image preloading awareness, loading states, empty views, and responsive breakpoints.

Basic Usage

Shortest Column Balance Algorithm

Interaction States

Loading and Empty States

Usage in Nuxt

The Waterfall component fully supports SSR in Nuxt 3/4. When used in a Nuxt project, it is auto-imported.

Nuxt Integration

SSR Considerations:

• ✅ Supports static rendering on first load to prevent layout shifts.
• ✅ Responsive column counts automatically adapt to container width after client-side hydration.

Commercial Case: E-commerce Pagination

Pagination Loading

Commercial Case: Infinite Loading Flow

Infinite Flow

API

Props

Name	Description	Type	Default
items	Data source array	T[]	[]
cols	Column count config. Supports a number or responsive object.	number | WaterfallCols	2
gap	Gap between cards (px)	number	16
loading	Whether in loading state	boolean	false
height-property	Field name for height used for balanced layout. Enables shortest column algorithm if provided.	string	'height'
img-selector	Internal image selector. Triggers re-calculation after images load.	string	'img'
animation	Whether entrance animations are enabled	boolean	true
delay	Base delay for step-up animations (ms)	number	100
row-key	Field name for unique identifier	string	'id'
responsive	Whether to automatically listen for container width changes	boolean	true
theme-overrides	Component-level theme overrides	ComponentThemeVars	undefined

WaterfallCols Definition

interface WaterfallCols {
  xs?: number // < 576px
  sm?: number // >= 576px
  md?: number // >= 768px
  lg?: number // >= 992px
  xl?: number // >= 1200px
}

Events

This component does not expose component events.

Slots

Name	Description	Parameters
default	Custom node rendering	{ item: T, index: number, column: number }
loading	Custom initial loading placeholder (usually skeletons)	-
empty	Custom empty state content	-
loading-overlay	Custom overlay for refresh states (when old data is present)	-

Expose

Name	Description	Type
layout	Manually trigger layout re-calculation	() => void

Theme Variables

YhWaterfall supports themeOverrides, but the current stylesheet does not declare component-scoped CSS variables. Loading placeholders, empty text, and refresh overlays consume shared global theme tokens directly.

Type Exports

Name	Description
YhWaterfallCols	Responsive column config type
YhWaterfallItemBase	Base item type
YhWaterfallProps	Component props type
YhWaterfallSlots	Component slots type
YhWaterfallExpose	Component expose type
YhWaterfallInstance	Component instance type