Vue Dragscroll Directive

4.0.6 · active · verified Sun Apr 19

vue-dragscroll is a lightweight Vue.js directive designed to enable scrolling of an HTML element via a drag-and-drop or click-and-hold mouse interaction. The current stable version, 4.0.6, is specifically built for Vue 3 projects and leverages modern tooling such as TypeScript and Vite. This package offers a simple, declarative way to implement interactive scrolling without needing complex configurations, distinguishing itself as a focused directive rather than a comprehensive scrolling utility. It provides an intuitive user experience for horizontally or vertically scrollable containers. Release cadence has historically been tied to major Vue version compatibility, with key updates like adding Vue 3 support and migrating to a TypeScript codebase.

Common errors

```
Failed to resolve directive: dragscroll
```
cause The `dragscroll` directive has not been properly registered with the Vue application instance.

fix Ensure you have globally registered the directive using `app.directive('dragscroll', dragscroll);` after importing `dragscroll`.
```
TypeError: Cannot read properties of undefined (reading 'directive') OR dragscroll is not a function
```
cause This typically occurs when attempting to use CommonJS `require()` syntax (`const dragscroll = require('vue-dragscroll');`) in a modern Vue 3 project that expects ESM, or when trying to access a non-existent default export.

fix Use the correct ES module named import: `import { dragscroll } from 'vue-dragscroll';`.
```
Module not found: Error: Can't resolve 'vue-dragscroll'
```
cause The package is not installed, or there's a typo in the import path.

fix Run `npm install vue-dragscroll` or `yarn add vue-dragscroll` to install the package. Double-check the import statement for typos.

Warnings

breaking Version 4.0.2 explicitly dropped support for Vue 2. Applications using `vue-dragscroll` with Vue 2 should remain on versions prior to 3.0.0 or migrate their entire application to Vue 3.
Fix: Upgrade to Vue 3 or pin `vue-dragscroll` to a version compatible with Vue 2 (e.g., <3.0.0).
breaking Version 3.0.0 introduced support for Vue 3. While a necessary upgrade for Vue 3 projects, it implies breaking changes for existing Vue 2 projects attempting to upgrade `vue-dragscroll` without also migrating Vue itself.
Fix: Ensure your project is running Vue 3 when using `vue-dragscroll` v3.x or v4.x. For Vue 2 projects, use `vue-dragscroll` versions <3.0.0.
breaking With the migration to TypeScript and Vite in v4.0.2, `vue-dragscroll` primarily targets ESM (ECMAScript Modules) environments. Attempting to use CommonJS `require()` syntax may lead to import errors or incorrect module resolution in modern Vue 3 setups.
Fix: Always use ES module import syntax (`import { dragscroll } from 'vue-dragscroll';`) when consuming the package in Vue 3 projects.

Install

npm install vue-dragscroll npm
yarn add vue-dragscroll yarn
pnpm add vue-dragscroll pnpm

Imports

dragscroll
wrong:
```
const dragscroll = require('vue-dragscroll');
```
correct:
```
import { dragscroll } from 'vue-dragscroll';
```
Since v4.0.2, the package is built with Vite and primarily targets ESM environments, making CommonJS 'require' syntax incompatible for modern Vue 3 projects.

Directive registration

wrong:

app.directive('dragscroll', require('vue-dragscroll').default);

correct:

import { createApp } from 'vue';
import { dragscroll } from 'vue-dragscroll';

const app = createApp(App);
app.directive('dragscroll', dragscroll);

The directive must be globally registered with `app.directive()` before use in components. The `dragscroll` symbol is a named export.

Type import
```
import type { DragscrollOptions } from 'vue-dragscroll';
```
The library ships with TypeScript types, allowing for type-checking of directive options or the directive instance itself, although direct configuration types are not frequently exposed.

Quickstart

This example demonstrates how to globally register the `dragscroll` directive and apply it to a scrollable `div` in a Vue 3 application. It creates a simple horizontal scroll container populated with items that can be scrolled by dragging with the mouse.

import { createApp } from 'vue';
import { dragscroll } from 'vue-dragscroll';

const app = createApp({
  template: `
    <div v-dragscroll class="scrollable-container">
      <div v-for="n in 10" :key="n" class="scroll-item">
        Item {{ n }}
      </div>
    </div>
  `,
  setup() {
    // Component logic here if needed
  }
});

app.directive('dragscroll', dragscroll);
app.mount('#app');

// Basic styling for demonstration purposes
const style = document.createElement('style');
style.innerHTML = `
.scrollable-container {
  width: 400px;
  height: 150px;
  overflow-x: scroll;
  overflow-y: hidden; /* Prevent vertical scrolling */
  white-space: nowrap;
  border: 1px solid #ccc;
  cursor: grab;
  user-select: none;
  padding: 10px;
}
.scrollable-container:active {
  cursor: grabbing;
}
.scroll-item {
  display: inline-block;
  width: 120px;
  height: 100%;
  background-color: #f0f0f0;
  margin-right: 10px;
  line-height: 130px;
  text-align: center;
  border: 1px dashed #aaa;
  vertical-align: middle;
}
`;
document.head.appendChild(style);

view raw JSON →