@sevenwu/vue-virtual-waterfull

A lightweight Vue 3 virtual waterfall component with infinite scroll and TypeScript support.

Features

• Vue 3 + TypeScript
• Virtualized waterfall layout
• Responsive columns
• Infinite scroll trigger
• Simple image-card default UI
• Slot support for custom item rendering

Install

npm install @sevenwu/vue-virtual-waterfull

Usage

<script setup lang="ts">
import { ref } from "vue";
import Waterfull, { type WaterfullItem } from "@sevenwu/vue-virtual-waterfull";
import "@sevenwu/vue-virtual-waterfull/style.css";

const items = ref<WaterfullItem[]>([
  {
    id: 1,
    title: "Card 1",
    description: "A simple waterfall card",
    image: "https://picsum.photos/seed/1/480/720",
    aspectRatio: 1.5,
  },
]);

const isLoading = ref(false);
const hasMore = ref(true);

const loadMore = async () => {
  isLoading.value = true;
  await new Promise((resolve) => setTimeout(resolve, 300));
  items.value.push({
    id: items.value.length + 1,
    title: `Card ${items.value.length + 1}`,
    image: `https://picsum.photos/seed/${items.value.length + 1}/480/640`,
    aspectRatio: 1.33,
  });
  isLoading.value = false;
};
</script>

<template>
  <div style="height: 80vh">
    <Waterfull
      :items="items"
      :is-loading="isLoading"
      :has-more="hasMore"
      :column-width="260"
      @load-more="loadMore"
    />
  </div>
</template>

Global install

import { createApp } from "vue";
import App from "./App.vue";
import Waterfull from "@sevenwu/vue-virtual-waterfull";
import "@sevenwu/vue-virtual-waterfull/style.css";

createApp(App).use(Waterfull).mount("#app");

Props

| Prop | Type | Default | | --- | --- | --- | | items | WaterfullItem[] | [] | | breakpoints | { minWidth: number; columns: number }[] | built-in | | columnWidth | number | 280 | | gap | number | 16 | | paddingX | number | 0 | | paddingTop | number | 0 | | paddingBottom | number | 0 | | estimatedItemHeight | number | 280 | | overscan | number | 400 | | loadMoreThreshold | number | 300 | | hasMore | boolean | false | | isLoading | boolean | false | | emptyText | string | "No items" | | loadingText | string | "Loading..." | | endText | string | "No more items" |

Events

• load-more
• select

Exports

import Waterfull, {
  Waterfull,
  useVirtualWaterfallScroll,
  type WaterfullItem,
  type WaterfullProps,
} from "vue-virtual-waterfull-prefect";
} from "@sevenwu/vue-virtual-waterfull";

Publish checklist

Before publishing a new release, check these fields in package.json:

• name if you want a different npm package name
• version when publishing a new release

Then run:

npm run build
npm pack --dry-run
npm publish

For a scoped public package, use:

npm publish --access public

Notes

• vue is declared as a peerDependency, which is the expected setup for a Vue component library.
• The package exports both the component and the useVirtualWaterfallScroll hook.
• The default export supports app.use() and direct component import.