### Install vue-waterfall-plugin-next

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Install the plugin using npm. This command is used for project setup.

```bash
npm install vue-waterfall-plugin-next
```

--------------------------------

### Waterfall Component Props Example

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Example of configuring the 'breakpoints' prop for responsive design. This allows the component to adjust the number of columns based on the container width.

```javascript
breakpoints: {
  1200: {
    // when wrapper width < 1200
    rowPerView: 3,
  },
  800: {
    // when wrapper width < 800
    rowPerView: 2,
  },
  500: {
    // when wrapper width < 500
    rowPerView: 1,
  },
}
```

--------------------------------

### Basic Waterfall Component Usage

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Demonstrates the basic setup of the Waterfall component with a list of items, custom breakpoints, and lazy loading enabled. Ensure 'vue-waterfall-plugin-next/dist/style.css' is imported for styling.

```vue
<template>
  <Waterfall
    :list="list"
    :row-key="'id'"
    :gutter="10"
    :width="320"
    :has-around-gutter="true"
    :breakpoints="breakpoints"
    :img-selector="'src'"
    :background-color="'#ffffff'"
    :animation-effect="'fadeIn'"
    :animation-duration="1000"
    :animation-delay="300"
    :lazyload="true"
    :load-props="loadProps"
    @afterRender="onAfterRender"
  >
    <template #default="{ item, url, index }">
      <div class="card">
        <LazyImg :url="url" :alt="item.name" />
        <div class="card-content">
          <h3>{{ item.name }}</h3>
          <p>{{ item.description }}</p>
        </div>
      </div>
    </template>
  </Waterfall>
</template>

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

const list = ref([
  { id: 1, name: 'Item 1', src: 'https://example.com/image1.jpg', description: 'Description 1' },
  { id: 2, name: 'Item 2', src: 'https://example.com/image2.jpg', description: 'Description 2' },
  { id: 3, name: 'Item 3', src: 'https://example.com/image3.jpg', description: 'Description 3' },
])

const breakpoints = {
  1200: { rowPerView: 4 },  // 4 columns when width < 1200px
  800: { rowPerView: 3 },   // 3 columns when width < 800px
  500: { rowPerView: 2 },   // 2 columns when width < 500px
}

const loadProps = {
  loading: '/assets/loading.png',
  error: '/assets/error.png',
}

function onAfterRender() {
  console.log('Layout rendering complete')
}
</script>
```

--------------------------------

### Animation Configuration with animate.css

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Configure entry animations using animate.css library for card entrance effects. Ensure `animate.css` is imported and the `animation-prefix` and `animation-effect` props are set accordingly.

```vue
<template>
  <Waterfall
    :list="items"
    :row-key="'id'"
    :animation-prefix="'animate__animated'"
    :animation-effect="'animate__fadeInUp'"
    :animation-duration="1000"
    :animation-delay="300"
    :animation-cancel="false"
    :pos-duration="300"
  >
    <template #default="{ item, url }">
      <div class="animated-card">
        <LazyImg :url="url" />
        <h4>{{ item.title }}</h4>
      </div>
    </template>
  </Waterfall>
</template>

<script setup>
import { ref } from 'vue'
import { Waterfall, LazyImg } from 'vue-waterfall-plugin-next'
import 'vue-waterfall-plugin-next/dist/style.css'
import 'animate.css'  // Required for animation effects

const items = ref([
  { id: 1, title: 'Animated Item 1', src: 'https://example.com/img1.jpg' },
  { id: 2, title: 'Animated Item 2', src: 'https://example.com/img2.jpg' },
])
</script>

<style>
/* If not using animate.css, add this for default fadeIn effect */
.animate__animated {
  animation-fill-mode: both;
  animation-duration: 1s;
}
</style>
```

--------------------------------

### Responsive Breakpoints Configuration

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Configure responsive column counts for different screen sizes using the `breakpoints` prop. This allows the layout to adapt automatically to various viewport widths.

```vue
<template>
  <Waterfall
    :list="gallery"
    :row-key="'id'"
    :width="300"
    :gutter="15"
    :space="20"
    :breakpoints="responsiveBreakpoints"
    :has-around-gutter="true"
    :align="'center'"
  >
    <template #default="{ item, url, index }">
      <div class="gallery-item">
        <LazyImg :url="url" />
        <div class="overlay">
          <span>Image {{ index + 1 }}</span>
        </div>
      </div>
    </template>
  </Waterfall>
</template>

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

const gallery = ref([
  { id: 1, src: 'https://example.com/gallery1.jpg' },
  { id: 2, src: 'https://example.com/gallery2.jpg' },
  { id: 3, src: 'https://example.com/gallery3.jpg' },
  { id: 4, src: 'https://example.com/gallery4.jpg' },
])

const responsiveBreakpoints = {
  1400: { rowPerView: 5 },  // Large desktop: 5 columns
  1200: { rowPerView: 4 },  // Desktop: 4 columns
  992: { rowPerView: 3 },   // Tablet landscape: 3 columns
  768: { rowPerView: 2 },   // Tablet portrait: 2 columns
  480: { rowPerView: 1 },   // Mobile: 1 column
}
</script>
```

--------------------------------

### LazyImg success Method

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Event emitted when the image successfully loads.

```APIDOC
## METHOD success

### Description
Event emitted when the image successfully loads.

### Method
EVENT

### Endpoint
@success

### Response
#### Success Response (200)
- **event** (string) - The native load event object.
```

--------------------------------

### Import and Use Waterfall Component

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Import the Waterfall component and its CSS. Initialize your data with a list of items, each containing a 'src' property for the image.

```javascript
import { LazyImg, Waterfall } from 'vue-waterfall-plugin-next'
import 'vue-waterfall-plugin-next/dist/style.css'

// 数据
data: {
  list: [
    {
      src: "xxxx.jpg",
      ...
    }
    ...
  ]
}
```

--------------------------------

### Configure Lazy Loading Properties

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Set placeholder images for loading and error states, and define a custom ratio calculator to control the aspect ratio of lazy-loaded images. The ratio calculator ensures images maintain a visually appealing aspect ratio within specified minimum and maximum bounds.

```javascript
import loading from 'assets/loading.png'
import error from 'assets/error.png'
loadProps: {
  loading,
  error,
  ratioCalculator: (width, height) => {
    // 我设置了最小宽高比
    const minRatio = 3 / 4;
    const maxRatio = 4 / 3;
    // 获取当前图片的比例
    const curRatio = width / height;
    // 如果当前图片比列不在此范围内，我们取最小或者最大值
    if (curRatio < minRatio) {
      return minRatio;
    } else if (curRatio > maxRatio) {
      return maxRatio;
    } else {
      return curRatio;
    }
  }
}
```

--------------------------------

### Infinite Scroll with Load More

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Implement infinite scroll pagination by appending items to the list array. Fetch products and load more on button click.

```vue
<template>
  <div class="container">
    <Waterfall
      :list="products"
      :row-key="'id'"
      :gutter="10"
      :breakpoints="breakpoints"
      :img-selector="'image.url'"
      :lazyload="true"
      :load-props="loadProps"
      @afterRender="onLayoutComplete"
    >
      <template #default="{ item, url, index }">
        <div class="product-card" @click="onCardClick(item)">
          <LazyImg :url="url" :alt="item.name" />
          <div class="product-info">
            <h3>{{ item.name }}</h3>
            <p class="price">${{ item.price }}</p>
            <button @click.stop="deleteItem(index)">Remove</button>
          </div>
        </div>
      </template>
    </Waterfall>

    <div class="load-more">
      <button :disabled="loading" @click="loadMore">
        {{ loading ? 'Loading...' : 'Load More' }}
      </button>
    </div>
  </div>
</template>

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

const products = ref([])
const page = ref(1)
const loading = ref(false)

const breakpoints = {
  1200: { rowPerView: 4 },
  800: { rowPerView: 3 },
  500: { rowPerView: 2 },
}

const loadProps = {
  loading: '/assets/loading.png',
  error: '/assets/error.png',
}

async function fetchProducts(pageNum) {
  const response = await fetch(`/api/products?page=${pageNum}&limit=20`)
  const data = await response.json()
  return data.products.map(item => ({
    id: item.id,
    name: item.title,
    price: item.variants[0].price,
    image: { url: item.images[0].src },
  }))
}

async function loadMore() {
  loading.value = true
  const newProducts = await fetchProducts(page.value)
  products.value.push(...newProducts)
  page.value++
  loading.value = false
}

function deleteItem(index) {
  products.value.splice(index, 1)
}

function onCardClick(item) {
  console.log('Card clicked:', item)
}

function onLayoutComplete() {
  console.log('Layout rendering finished')
}

onMounted(() => {
  loadMore()
})
</script>
```

--------------------------------

### LazyImg error Method

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Event emitted when the image fails to load.

```APIDOC
## METHOD error

### Description
Event emitted when the image fails to load.

### Method
EVENT

### Endpoint
@error

### Response
#### Success Response (200)
- **event** (string) - The native error event object.
```

--------------------------------

### LazyImg load Method

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Event emitted when the `<img>` tag's load function is triggered.

```APIDOC
## METHOD load

### Description
Event emitted when the `<img>` tag's load function is triggered.

### Method
EVENT

### Endpoint
@load

### Response
#### Success Response (200)
- **event** (string) - The native load event object.
```

--------------------------------

### LazyImg Component Props

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Configurable properties for the "LazyImg" component to control image loading behavior.

```APIDOC
## COMPONENT LazyImg

### Description
Configurable properties for the `LazyImg` component to control image loading behavior.

### Method
PROPS

### Endpoint
<LazyImg :props="{...}"></LazyImg>

### Parameters
#### Request Body
- **ratio** (Number) - Optional - 图片的默认比列，如果你提前知道图片的大小，可以根据width和height算出来传进来，这样可以在图片完全加载前固定位置，视觉效果好很多. Default: `1`

### Request Example
```json
{
  "url": "image.jpg",
  "ratio": 1.5
}
```
```

--------------------------------

### Custom Lazy Loading Configuration

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Configure custom loading and error images for the LazyImg component within the Waterfall. A custom ratioCalculator is provided to manage aspect ratios. Ensure CSS is imported.

```vue
<template>
  <Waterfall
    :list="products"
    :row-key="'id'"
    :img-selector="'images.thumbnail'"
    :load-props="loadProps"
    :lazyload="true"
    :cross-origin="true"
  >
    <template #default="{ item, url }">
      <div class="product-card">
        <LazyImg :url="url" />
        <span class="price">${{ item.price }}</span>
      </div>
    </template>
  </Waterfall>
</template>

<script setup>
import { ref } from 'vue'
import { Waterfall, LazyImg } from 'vue-waterfall-plugin-next'
import 'vue-waterfall-plugin-next/dist/style.css'
import loadingImg from './assets/loading.png'
import errorImg from './assets/error.png'

const products = ref([
  { id: 1, price: 29.99, images: { thumbnail: 'https://example.com/thumb1.jpg' } },
  { id: 2, price: 49.99, images: { thumbnail: 'https://example.com/thumb2.jpg' } },
])

const loadProps = {
  loading: loadingImg,
  error: errorImg,
  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
  },
}
</script>
```

--------------------------------

### Waterfall renderer Method

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Manually re-renders the waterfall layout. Useful when using other lazy loading components or needing to force a layout update.

```APIDOC
## METHOD renderer

### Description
Manually re-renders the waterfall layout. This method can be called directly to redraw the list, especially useful in callback functions of other lazy loading image components to force a redraw.

### Method
METHOD

### Endpoint
waterfallRef.value.renderer()

### Request Example
```javascript
const waterfall = ref(null)
waterfall.value.renderer()
```

### Response
#### Success Response (200)
- No explicit return value mentioned, implies a void operation.
```

--------------------------------

### Custom LazyImg Styling

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Style lazy loading images based on their loading state using CSS attribute selectors. This allows for custom placeholders and transitions.

```vue
<template>
  <Waterfall :list="images" :row-key="'id'" :lazyload="true">
    <template #default="{ item, url }">
      <div class="image-container">
        <LazyImg :url="url" :ratio="item.aspectRatio" />
      </div>
    </template>
  </Waterfall>
</template>

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

const images = ref([
  { id: 1, src: 'https://example.com/img1.jpg', aspectRatio: 0.75 },
  { id: 2, src: 'https://example.com/img2.jpg', aspectRatio: 1.33 },
])
</script>

<style>
/* Loading state - show spinner placeholder */
.lazy__img[lazy="loading"] {
  padding: 5em 0;
  width: 48px;
  opacity: 0.5;
}

/* Loaded state - full width image */
.lazy__img[lazy="loaded"] {
  width: 100%;
  height: 100%;
  object-fit: cover;
  transition: opacity 0.3s ease;
}

/* Error state - show error placeholder */
.lazy__img[lazy="error"] {
  padding: 5em 0;
  width: 48px;
  filter: grayscale(100%);
}
</style>
```

--------------------------------

### LazyImg Component Usage

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Utilize the LazyImg component for efficient image loading with IntersectionObserver. It supports loading and error states. Import the component and CSS. Event handlers for load, success, and error are demonstrated.

```vue
<template>
  <div class="image-gallery">
    <LazyImg
      :url="imageUrl"
      :title="'Product Image'"
      :alt="'Product thumbnail'"
      :ratio="0.75"
      @load="onImageLoad"
      @success="onImageSuccess"
      @error="onImageError"
    />
  </div>
</template>

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

const imageUrl = 'https://example.com/product.jpg'

function onImageLoad(url) {
  console.log(`Image loaded: ${url}`)
}

function onImageSuccess(url) {
  console.log(`Image successfully displayed: ${url}`)
}

function onImageError(url) {
  console.error(`Failed to load image: ${url}`)
}
</script>
```

--------------------------------

### Custom Lazy Loading Image Styles

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Apply custom CSS to style images based on their lazy loading state. Styles can be defined for images that are currently loading, have successfully loaded, or have encountered an error during loading.

```css
.lazy__img[lazy=loading] {
  padding: 5em 0;
  width: 48px;
}

.lazy__img[lazy=loaded] {
  width: 100%;
}

.lazy__img[lazy=error] {
  padding: 5em 0;
  width: 48px;
}
```

--------------------------------

### Horizontal Ordering Mode

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Enable horizontal ordering to arrange cards left-to-right instead of filling shortest columns first. Items will be arranged in order: 1, 2, 3, 4 (left to right).

```vue
<template>
  <Waterfall
    :list="items"
    :row-key="'id'"
    :gutter="10"
    :horizontal-order="true"
    :height-difference="10"
    :align="'left'"
  >
    <template #default="{ item, url, index }">
      <div class="ordered-card">
        <LazyImg :url="url" />
        <span class="index-badge">{{ index + 1 }}</span>
      </div>
    </template>
  </Waterfall>
</template>

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

// Items will be arranged in order: 1, 2, 3, 4 (left to right)
// Instead of default behavior: filling shortest column first
const items = ref([
  { id: 1, src: 'https://example.com/img1.jpg' },
  { id: 2, src: 'https://example.com/img2.jpg' },
  { id: 3, src: 'https://example.com/img3.jpg' },
  { id: 4, src: 'https://example.com/img4.jpg' },
])
</script>
```

--------------------------------

### Waterfall afterRender Method

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Event emitted when card coordinate calculation is complete and cards have moved to their positions.

```APIDOC
## METHOD afterRender

### Description
This event is triggered when the card coordinate calculation is completed and the cards have moved to their corresponding positions. This process might be triggered multiple times, for example, when an image finishes loading, the positions are recalculated.

### Method
EVENT

### Endpoint
@afterRender

### Response
#### Success Response (200)
- No explicit return value mentioned, implies a void event.
```

--------------------------------

### Waterfall Component Template

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Use the Waterfall component in your template, providing the 'list' data. The default slot receives 'item', 'url', and 'index' for rendering each card. Use LazyImg for image loading.

```html
<Waterfall :list="list">
  <!-- v2.6.0之前版本插槽数据获取 -->
  <!-- <template #item="{ item, url, index }">
  <!-- 新版插槽数据获取 -->
  <template #default="{ item, url, index }">
    <div class="card">
      <LazyImg :url="url" />
      <p class="text">这是具体内容</p>
    </div>
  </template>
</Waterfall>
```

--------------------------------

### Force Re-render Layout

Source: https://context7.com/heikaimu/vue3-waterfall-plugin/llms.txt

Manually trigger layout recalculation using the exposed `renderer` method. This is useful when using external lazy loading libraries or when content dimensions change dynamically after initial render.

```vue
<template>
  <div>
    <Waterfall ref="waterfallRef" :list="items" :row-key="'id'">
      <template #default="{ item, url }">
        <div class="card">
          <img :src="url" @load="onExternalImageLoad" />
          <p>{{ item.title }}</p>
        </div>
      </template>
    </Waterfall>
    <button @click="forceRender">Recalculate Layout</button>
  </div>
</template>

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

const waterfallRef = ref(null)
const items = ref([
  { id: 1, title: 'Card 1', src: 'https://example.com/img1.jpg' },
  { id: 2, title: 'Card 2', src: 'https://example.com/img2.jpg' },
])

function forceRender() {
  waterfallRef.value?.renderer()
}

function onExternalImageLoad() {
  // Trigger re-layout after external image loads
  waterfallRef.value?.renderer()
}
</script>
```

--------------------------------

### Waterfall Component Props

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Configurable properties for the "Waterfall" component to control layout, appearance, and behavior.

```APIDOC
## COMPONENT Waterfall

### Description
Configurable properties for the `Waterfall` component to control layout, appearance, and behavior.

### Method
PROPS

### Endpoint
<Waterfall :props="{...}"></Waterfall>

### Parameters
#### Request Body
- **list** (Array) - Optional - 列表数据. Default: `[]`
- **rowKey** (String) - Optional - 数据唯一的字段，比如列表里面的`id`, 如果要删除卡片，该字段为必填. Default: `id`
- **imgSelector** (String) - Optional - 图片字段选择器，如果层级较深，使用 `xxx.xxx.xxx` 方式. Default: `src`
- **width** (Number) - Optional - 卡片在 PC 上的宽度, 与breakpoints一样可以确定卡片的宽度以及每行个数, 但**breakpoints优先级高于width**. Default: `200`
- **breakpoints** (Object) - Optional - 类似css的@media, 定义不同容器宽度下每行卡片个数，主要用于对移动端的适配. Default: `{1200:{rowPerView:3},800:{rowPerView:2},500:{rowPerView:1}}`
- **gutter** (Number) - Optional - 卡片之间的间隙. Default: `10`
- **space** (Number) - Optional - 这是行间隙，如果不设置他，列和行都会用gutter. Default: `10`
- **hasAroundGutter** (Boolean) - Optional - 容器四周是否有 `gutter` 边距. Default: `true`
- **posDuration** (Number) - Optional - 卡片移动到正确位置的动画时间. Default: `300`
- **animationPrefix** (String) - Optional - 详情见下文《动画样式》. Default: `animate__animated`
- **animationEffect** (String) - Optional - 卡片入场动画，默认只有 `fadeIn`，引入 `animation.css` 后可使用其他动画. Default: `fadeIn`
- **animationDuration** (Number) - Optional - 卡片入场动画执行时间（单位毫秒）,该动画时间只影响卡片重拍的时间，一般情况都不用修改，如果想要修改飞入动画的执行时间，见下文. Default: `1000`
- **animationDelay** (Number) - Optional - 卡片入场动画延迟（单位毫秒）. Default: `300`
- **animationCancel** (Boolean) - Optional - 取消动画，开启后，所有动画属性都不生效. Default: `false`
- **backgroundColor** (String) - Optional - 背景颜色. Default: `#ffffff`
- **loadProps** (Object) - Optional - 懒加载图片组件的属性设置，详情见下文《懒加载属性》. Default: `loadProps`
- **lazyload** (Boolean) - Optional - 是否开启懒加载. Default: `true`
- **crossOrigin** (Boolean) - Optional - 图片加载是否开启跨域. Default: `true`
- **delay** (Number) - Optional - 布局刷新的防抖时间，默认 `300ms` 内没有再次触发才刷新布局。（图片加载完成；容器大小、`list`、`width`、`gutter`、`hasAroundGutter`变化时均会触发刷新）. Default: `300`
- **align** (String) - Optional - 卡片的对齐方式，可选值为：`left`,`center`,`right`. Default: `center`
- **horizontalOrder** (Boolean) - Optional - 卡片是否按照从左到右的顺序排列，默认情况是，那里高度最低排哪里. Default: `false`
- **heightDifference** (Number) - Optional - 在horizontalOrder为false的情况下，在高度差距距离最小值10以内，取index最小的列作为下一个卡片的列. Default: `0`

### Request Example
```json
{
  "list": [
    {
      "src": "image1.jpg",
      "id": 1
    }
  ],
  "width": 250,
  "gutter": 15
}
```
```

--------------------------------

### Force Update Waterfall Component

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Manually trigger a re-render of the waterfall list by calling the 'renderer' method on the component's ref. This is useful when integrating with custom image loading callbacks.

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

const waterfall = ref(null)
waterfall.value.renderer()
```

--------------------------------

### Custom Animation CSS

Source: https://github.com/heikaimu/vue3-waterfall-plugin/blob/master/README.md

Define custom CSS for the default 'fadeIn' animation if not using an external library like animate.css. This ensures the animation-fill-mode and duration are correctly applied.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.