vue-waterfall-plugin-next

Animations in this plugin apply when new data is inserted. To use custom animations, you must include animate.css (v4+ works out of the box; for older versions, set animationPrefix to 'animated').

If you do not want to include animate.css and only want the default fadeIn effect, add this to your CSS:

.animate__animated {
  animation-fill-mode: both;
  animation-duration: 1s;
}

Note: animation-duration in your CSS controls the speed of the 'fly-in' animation.

To use the Vue3 waterfall component, install the package using npm:

npm install vue-waterfall-plugin-next

A ViewCard is the fundamental data unit for the waterfall. It is a generic object (Record<string, any>) representing a single item in the waterfall list. You can attach any properties to this object that your custom item component requires.

export type ViewCard = Record<string, any>

The breakpoints prop allows you to define how many cards appear per row based on the container width, similar to CSS media queries. When breakpoints are active, the width prop is ignored.

Example configuration:

breakpoints: {
  1200: { rowPerView: 3 }, // When width < 1200
  800: { rowPerView: 2 }, // When width < 800
  500: { rowPerView: 1 }, // When width < 500
}

breakpoints: {
  1200: {
    rowPerView: 3,
  },
  800: {
    rowPerView: 2,
  },
  500: {
    rowPerView: 1,
  },
}

The loadProps object passed to Waterfall configures the LazyImg component. You can provide custom loading and error images, and a ratioCalculator to control the aspect ratio of the image placeholder before the actual image loads.

ratioCalculator receives (width, height) and should return the desired ratio. This helps prevent layout shifts by fixing the image area size.

import loading from 'assets/loading.png'
import error from 'assets/error.png'

const loadProps = {
  loading,
  error,
  ratioCalculator: (width, height) => {
    const minRatio = 3 / 4;
    const maxRatio = 4 / 3;
    const curRatio = width / height;
    if (curRatio < minRatio) return minRatio;
    if (curRatio > maxRatio) return maxRatio;
    return curRatio;
  }
}

Breakpoints allow you to define different layout configurations based on the container width. The Breakpoints type is a record where the key is the screen width (number) and the value is a Point object containing layout settings like rowPerView.

Example structure:

const breakpoints: Breakpoints = {
  768: { rowPerView: 2 },
  1200: { rowPerView: 4 }
};

export type Breakpoints = Record<number, Point>

interface Point {
  rowPerView: number
}

To implement a waterfall layout, import Waterfall and LazyImg from vue-waterfall-plugin-next. You must also import the component's CSS. Use the #default slot to define how each item in your list is rendered. The slot provides item (the data object), url (the image source), and index.

<script setup>
import { LazyImg, Waterfall } from 'vue-waterfall-plugin-next'
import 'vue-waterfall-plugin-next/dist/style.css'

const list = [
  { id: 1, src: 'xxxx.jpg' },
  // ...
]
</script>

<template>
<Waterfall :list="list">
  <template #default="{ item, url, index }">
    <div class="card">
      <LazyImg :url="url" />
      <p class="text">{{ item.text }}</p>
    </div>
  </template>
</Waterfall>
</template>

The LazyImg component is used within the Waterfall slot to handle image loading.

Props:

• ratio (Number, default 1): The default aspect ratio. Providing this allows the component to reserve the correct space before the image loads.

Events/Methods:

• load: Triggered by the img tag's load event.
• success: Triggered when the image loads successfully.
• error: Triggered when the image fails to load.

The Waterfall component exposes a renderer() method. You can use a template ref to access the component instance and call renderer() to manually force a layout recalculation. This is useful when using external lazy-loading callbacks that need to trigger a refresh.

<Waterfall ref="waterfall"></Waterfall>

<script setup>
import { ref } from 'vue'
const waterfall = ref(null)

// Call this to force a redraw
const refresh = () => {
  waterfall.value.renderer()
}
</script>

The vue3-waterfall-plugin package provides three main components for implementing waterfall layouts in Vue 3: Waterfall for standard layouts, WaterfallVirtual for virtualized large lists, and LazyImg for optimized image loading within the waterfall.

import { Waterfall, WaterfallVirtual, LazyImg } from 'vue3-waterfall-plugin-next';