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.
Interaction States
Usage in Nuxt
The Waterfall component fully supports SSR in Nuxt 3/4. When used in a Nuxt project, it is auto-imported.
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
Commercial Case: Infinite Loading 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 |