v-scroll-detect

English | 中文

English

A Vue directive based on ResizeObserver that automatically detects changes in element content and adds/removes CSS classes when vertical or horizontal scrollbars appear.

Features

• Auto Response: Listens not only to window resizing but also to internal content changes (e.g., async data loading).
• Performance Optimized: Uses ResizeObserver combined with requestAnimationFrame, more efficient than traditional onscroll or timer polling.
• Highly Decoupled: Can be reused on any container without writing complex DOM logic in components.
• Modern Compatibility: Supports all modern browsers (Chrome 64+, Firefox 69+, Safari 13.1+, Edge 79+).

Installation

npm install v-scroll-detect

Usage

Global Registration

import { createApp } from 'vue';
import App from './App.vue';
import vScrollDetect from 'v-scroll-detect';

const app = createApp(App);
app.use(vScrollDetect);
app.mount('#app');

Use in template:

<div v-scroll-detect="'has-scroll'">
  <!-- content -->
</div>

Local Registration

import { vScrollDetect } from 'v-scroll-detect';

export default {
  directives: {
    scrollDetect: vScrollDetect
  }
}

Or with <script setup>:

<script setup>
import { vScrollDetect } from 'v-scroll-detect';
</script>

<template>
  <div v-scroll-detect>
    <!-- content -->
  </div>
</template>

Vanilla JS

import { createScrollDetector } from 'v-scroll-detect';

const el = document.querySelector('.my-container');
const detector = createScrollDetector(el, 'has-scroll');

// To clean up
// detector.destroy();

React

import { useRef } from 'react';
import { useScrollDetect } from 'v-scroll-detect/react';

function MyComponent() {
  const scrollRef = useRef(null);
  useScrollDetect(scrollRef, 'with-scroll');

  return (
    <div ref={scrollRef}>
      {/* content */}
    </div>
  );
}

Options

0. No Parameters (Default Mode) Just use v-scroll-detect. It will add the default class with-scroll when any scrollbar appears.

   <div v-scroll-detect>...</div>

1. String (Simple Mode) Pass a class name string. It will be added when any scrollbar appears.

   <div v-scroll-detect="'with-scroll'">...</div>

2. Object (Advanced Mode) Pass an object to distinguish between vertical and horizontal scrollbars.

   <div v-scroll-detect="{ v: 'has-v-scroll', h: 'has-h-scroll' }">...</div>

   • v or vertical: Class for vertical scrollbar.
   • h or horizontal: Class for horizontal scrollbar.

中文

这是一个基于 ResizeObserver 封装的 Vue 指令。它能实时监听元素内容的变化，并在垂直或水平滚动条出现时，自动为该元素添加或移除指定的 CSS 类。

技术优势

• 自动响应：不仅监听窗口大小，还能监听内部内容（如异步加载数据后）的变化。
• 性能优化：通过 ResizeObserver 配合 requestAnimationFrame，比传统的 onscroll 或定时器检测更省 CPU。
• 高度解耦：作为指令，可以复用到任何容器上，无需在业务组件里写复杂的 DOM 逻辑。
• 2026 兼容性：ResizeObserver 已在所有主流浏览器中得到完美支持。

安装

npm install v-scroll-detect

使用方法

全局注册

import { createApp } from 'vue';
import App from './App.vue';
import vScrollDetect from 'v-scroll-detect';

const app = createApp(App);
app.use(vScrollDetect); // 默认指令名为 v-scroll-detect
app.mount('#app');

在模板中使用：

<div v-scroll-detect="'has-scroll'">
  <!-- 内容 -->
</div>

局部注册

import { vScrollDetect } from 'v-scroll-detect';

export default {
  directives: {
    scrollDetect: vScrollDetect
  }
}

或者在 <script setup> 中：

<script setup>
import { vScrollDetect } from 'v-scroll-detect';
</script>

<template>
  <div v-scroll-detect>
    <!-- 内容 -->
  </div>
</template>

原生 JavaScript (Vanilla JS)

import { createScrollDetector } from 'v-scroll-detect';

const el = document.querySelector('.my-container');
const detector = createScrollDetector(el, 'has-scroll');

// 销毁监听
// detector.destroy();

React

import { useRef } from 'react';
import { useScrollDetect } from 'v-scroll-detect/react';

function MyComponent() {
  const scrollRef = useRef(null);
  useScrollDetect(scrollRef, 'with-scroll');

  return (
    <div ref={scrollRef}>
      {/* 内容 */}
    </div>
  );
}

配置选项

0. 不传参数 (默认模式) 直接使用 v-scroll-detect。当出现任意滚动条时，会自动添加默认类名 with-scroll。

   <div v-scroll-detect>...</div>

1. 字符串 (简单模式) 传入一个类名字符串。当出现任意滚动条时，该类名会被添加。

   <div v-scroll-detect="'with-scroll'">...</div>

2. 对象 (进阶模式) 传入一个对象，区分横向和纵向滚动条。

   <div v-scroll-detect="{ v: 'has-v-scroll', h: 'has-h-scroll' }">...</div>

   • v or vertical: 垂直滚动条出现的类名。
   • h or horizontal: 水平滚动条出现的类名。