v3-waterfall

To improve performance with large amounts of data, you can enable virtual list support using virtualTime and virtualLength:

• virtualTime: The interval (in ms) after a scroll event to trigger virtual list calculations. Set this to 400 or higher for optimal use. A value of 0 disables the virtual list.
• virtualLength: The distance (in px) an element can move outside the viewport (above or below) before it is hidden.

Note: Because the component requires pre-rendering for layout calculations, the virtual list behavior may differ slightly from standard implementations.

To handle large datasets efficiently, enable virtual list support by setting virtualTime.

• virtualTime: The interval (in ms) after a scroll event to trigger virtual list calculations. Set this to 0 to disable. A value of 400 or higher is recommended.
• virtualLength: The distance (in px) an element can move outside the viewport before it is hidden.

The following changes are required when upgrading from v1 to v2:

• mobileGap: Deprecated. This field has been removed. Use the functional approach for gap to handle mobile spacing instead.
• srcKey: Deprecated. This field (used to specify the image URL field in the list) has been removed.

New requirement for images: Since srcKey is removed, you must now add a data-key attribute to every <img> tag within your card slot that dynamically affects the card's height. Refer to the main README for specific implementation details on using data-key.

To use v3-waterfall in your Vue 3 project, install it via npm and register it as a plugin in your main entry file. You must also import the component's CSS file to ensure correct layout and styling.

npm i v3-waterfall

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import V3waterfall from 'v3-waterfall'
import 'v3-waterfall/dist/style.css'

createApp(App)
  .use(V3waterfall)
  .mount('#app')

By default, the component listens to the window scroll event. If your waterfall is inside a specific container with overflow-y: scroll, you must use scrollBodySelector and isMounted together.

Because the child component's mounted hook runs before the parent's, you must use a ref to track when the parent component has finished mounting and pass that to :isMounted.

<div class="father-box">
  <v3-waterfall scrollBodySelector=".father-box" :isMounted="isMounted"></v3-waterfall>
</div>

<script setup>
import { ref, onMounted } from 'vue'
const isMounted = ref(false)

onMounted(() => {
  isMounted.value = true
})
</script>

<style>
.father-box {
  height: 300px;
  overflow-y: scroll;
}
</style>

To use v3-waterfall in your Vue 3 project, install it via pnpm and register it as a plugin in your main entry file. You must also import the component's CSS file for correct styling.

pnpm add v3-waterfall

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import V3waterfall from 'v3-waterfall'
import 'v3-waterfall/dist/style.css'

createApp(App).use(V3waterfall).mount('#app')

In v2, the component no longer includes built-in logic for detecting mobile devices. To support responsive layouts (different widths/gaps for mobile vs. PC), you must change the colWidth, gap, and bottomGap properties from static number values to a function type: number | () => number.

Use the returned value of the function to define the specific pixel value based on your own device detection logic.

// Example of implementing responsive width using a function
const getColWidth = () => {
  const device = /(Android|iPhone|iPod|iOS|SymbianOS|Windows Phone)/gi.test(userAgent)
    ? 'mobile'
    : /iPad/gi.test(userAgent)
      ? 'ipad'
      : 'pc'

  const widthMap = {
    mobile: 200,
    ipad: 250,
    pc: 250
  }
  return widthMap[device]
}

// Apply to component props
// <v3-waterfall :col-width="getColWidth" ... />

To use v3-waterfall in your Vue application, you can install it as a global plugin. This registers the V3waterfall component globally, allowing you to use it in any template within your app without manual imports.

import { createApp } from 'vue'
import V3waterfall from 'v3-waterfall'

const app = createApp(App)

// Install the plugin
app.use(V3waterfall)

app.mount('#app')

You can access the following methods via a component ref to handle specific UI updates:

• reRender(): Recalculates heights for all currently loaded cards. Use this when card content changes (e.g., toggling visibility of titles).
• insertBefore(insertList): Inserts a new list of items at the beginning of the current list. This is ideal for 'pull-to-refresh' scenarios. It does not recalculate heights for existing cards.

<script setup lang="ts">
import { ref } from 'vue'
import type { V3WaterfallExpose } from 'v3-waterfall'

const v3WaterfallRef = ref<V3WaterfallExpose | null>(null)

const handleRefresh = async () => {
  const newData = [/* ... */]
  await v3WaterfallRef.value?.insertBefore(newData)
}

const handleContentChange = () => {
  v3WaterfallRef.value?.reRender()
}
</script>

<template>
  <v3-waterfall ref="v3WaterfallRef" :list="list" />
</template>