Vue Utility Components

0.4.65 · active · verified Sun Apr 19

vueuc is a collection of essential utility components designed for Vue 3 applications, currently at version 0.4.65. This library provides specialized components such as `VBinder` for advanced element positioning and tracking, `VVirtialList` for efficient rendering of large datasets with variable-height items, `VXScroll` for horizontal scrolling via vertical mouse wheel input, and `VResizeObserver` for observing element dimension changes. The library's development and maintenance are primarily driven by a single developer, as explicitly stated in the README, which implies a potentially less formal release cadence and documentation style. Its key differentiator lies in offering low-level UI utilities focused on specific interaction patterns and performance optimizations (like virtualization), distinguishing it from broader UI component libraries. Users should note that detailed API documentation might be sparse, often requiring consultation of the source code.

Common errors

```
[Vue warn]: Failed to resolve component: v-binder
```
cause The `VBinder` component (or other vueuc components) was used in a Vue template without being properly imported and registered in the current component scope.

fix Ensure `import { VBinder } from 'vueuc';` is present in the `<script setup>` block, or explicitly registered in the `components` option of a standard Vue component.
```
Peer dependency 'vue@^3.0.11' not installed.
```
cause The `vueuc` package requires Vue 3 as a peer dependency, but a compatible version is not installed in the project.

fix Install a compatible version of Vue 3: `npm install vue@^3.0.11` or `yarn add vue@^3.0.11`.

Warnings

gotcha The official README explicitly states the author is 'too lazy to write' detailed API documentation, implying users will need to consult the source code for full API usage and behavior. This can make initial adoption and debugging more challenging.
Fix: Allocate time for source code review for detailed API understanding. Consider contributing to documentation if using in a large project.
breaking As the library is pre-1.0 (currently 0.4.65) and maintained by a single developer for personal use, breaking changes may occur more frequently without following semantic versioning strictly, potentially affecting minor version updates.
Fix: Pin exact versions (`"vueuc": "0.4.65"`) in `package.json` to prevent unexpected breaking changes on update. Review changelog or commit history thoroughly before upgrading.
gotcha The components like `VBinder` and `VFollower` require careful setup of `v-target` and `v-follower` within a `v-binder` scope. Misconfiguration can lead to elements not positioning correctly or failing to appear.
Fix: Always wrap a single `v-target` and one or more `v-follower` components within `v-binder`. Pay close attention to `placement` and `show` props on `v-follower`.

Install

npm install vueuc npm
yarn add vueuc yarn
pnpm add vueuc pnpm

Imports

VBinder
wrong:
```
import VBinder from 'vueuc';
```
correct:
```
import { VBinder } from 'vueuc';
```
Components are exported as named exports. Vue 3 components are typically used directly in the template after import.
VVirtialList
wrong:
```
const VVirtialList = require('vueuc');
```
correct:
```
import { VVirtialList } from 'vueuc';
```
This library is designed for modern JavaScript environments and ships with ESM exports and TypeScript types. CommonJS `require` is not the recommended or idiomatic way to import.
VResizeObserver
wrong:
```
import { ResizeObserver } from 'vueuc';
```
correct:
```
import { VResizeObserver } from 'vueuc';
```
Ensure correct component capitalization (`VResizeObserver`) as exported by the library, not the native DOM API name.

Quickstart

Demonstrates the usage of `VBinder`, `VTarget`, and `VFollower` for element positioning, along with `VVirtialList` for rendering a large, scrollable list efficiently in a Vue 3 component using `<script setup>`.

<template>
  <div style="height: 200px; padding: 50px; border: 1px solid #ccc;">
    <p>Target element below:</p>
    <v-binder>
      <v-target>
        <div ref="targetEl" style="width: 100px; height: 50px; background-color: lightblue; text-align: center; line-height: 50px;">
          Target
        </div>
      </v-target>
      <v-follower :show="true" placement="bottom-start" :overlap="true" :width="100">
        <div style="background-color: lightcoral; padding: 10px; border: 1px solid red;">
          Follower content
          <br>
          (Bottom-start)
        </div>
      </v-follower>
       <v-follower :show="true" placement="top-end" :overlap="true" :width="100">
        <div style="background-color: lightgreen; padding: 10px; border: 1px solid green;">
          Follower content
          <br>
          (Top-end)
        </div>
      </v-follower>
    </v-binder>
    <p style="margin-top: 20px;">Scroll down to see virtual list example.</p>
  </div>

  <div style="height: 300px; border: 1px solid #eee; margin-top: 20px;">
    <h3 style="margin: 0; padding: 10px;">Virtual List Example</h3>
    <v-virtual-list
      :items="items"
      :item-height="50"
      :height="250"
      style="border: 1px solid blue; overflow: auto;"
    >
      <template #default="{ item, index }">
        <div :key="item.id" style="height: 50px; display: flex; align-items: center; padding-left: 10px; border-bottom: 1px solid #f0f0f0;">
          Item {{ item.text }} - {{ index }}
        </div>
      </template>
    </v-virtual-list>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { VBinder, VTarget, VFollower, VVirtialList } from 'vueuc';

const targetEl = ref<HTMLElement | null>(null);

const items = Array.from({ length: 1000 }, (_, i) => ({
  id: i,
  text: `Content for item ${i}`,
}));
</script>

<style>
body { margin: 0; font-family: sans-serif; }
</style>

view raw JSON →