Skip to content
Latestv1.0.63

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 ​

NameDescriptionTypeDefault
itemsData source arrayT[][]
colsColumn count config. Supports a number or responsive object.number | WaterfallCols2
gapGap between cards (px)number16
loadingWhether in loading statebooleanfalse
height-propertyField name for height used for balanced layout. Enables shortest column algorithm if provided.string'height'
img-selectorInternal image selector. Triggers re-calculation after images load.string'img'
animationWhether entrance animations are enabledbooleantrue
delayBase delay for step-up animations (ms)number100
row-keyField name for unique identifierstring'id'
responsiveWhether to automatically listen for container width changesbooleantrue
theme-overridesComponent-level theme overridesComponentThemeVarsundefined

WaterfallCols Definition ​

ts
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 ​

NameDescriptionParameters
defaultCustom node rendering{ item: T, index: number, column: number }
loadingCustom initial loading placeholder (usually skeletons)-
emptyCustom empty state content-
loading-overlayCustom overlay for refresh states (when old data is present)-

Expose ​

NameDescriptionType
layoutManually 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 ​

NameDescription
YhWaterfallColsResponsive column config type
YhWaterfallItemBaseBase item type
YhWaterfallPropsComponent props type
YhWaterfallSlotsComponent slots type
YhWaterfallExposeComponent expose type
YhWaterfallInstanceComponent instance type

Released under the MIT License.