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

Waterfall Content Card #1

Shortest column balancing algorithm for a cleaner aesthetic.

Waterfall Content Card #5

Staggered entrance animations.

Waterfall Content Card #2

Basic demonstration node.

Waterfall Content Card #6

Basic demonstration node.

Waterfall Content Card #3

Supports image load awareness.

Waterfall Content Card #4

Responsive auto-alignment.

Shortest Column Balance Algorithm

Interaction States

Waterfall Content Card #1

Waterfall Content Card #5

Waterfall Content Card #2

Waterfall Content Card #6

Waterfall Content Card #3

Waterfall Content Card #4

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.

Waterfall Content Card #1

Waterfall Content Card #5

Waterfall Content Card #2

Waterfall Content Card #6

Waterfall Content Card #3

Waterfall Content Card #4

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

No Data

• 1
• 2
• 3
• 4
• 5
• 6
• ...
• 13

Pagination Loading

Commercial Case: Infinite Loading Flow

No Data

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

WaterfallCols Definition

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

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

Customize local styles by overriding these CSS variables:

Variable Name	Description	Default
--yh-bg-color-page	Background for skeleton nodes	var(--yh-bg-color-page)
--yh-color-text-secondary	Empty state text color	var(--yh-text-color-secondary)
--yh-color-primary	Loader rotation color for refresh overlay	var(--yh-color-primary)
--yh-color-primary-light-8	Loader orbit background for refresh overlay	var(--yh-color-primary-light-8)