Vue Table Touch Scroll

vue-table-touch-scroll is a lightweight solution dedicated to bridging the gap between desktop tables and mobile touch interactions. With a simple directive, it ensures that any Vue PC table component delivers a native-grade, silky-smooth scrolling and interaction experience on mobile devices. This includes seamless out-of-the-box support for table components in mainstream UI libraries like Element Plus, Ant Design Vue, and Naive UI.

✨ Features

• 🚀 Easy to Use - Simple directive-based API
• ⚡️ Lightweight - Zero dependencies, minimal bundle size
• 📱 Touch & Mouse Support - Works on both mobile and desktop devices
• 🎯 UI Library Presets - Built-in scroll container selectors for popular UI libraries
• 🔧 TypeScript - Full TypeScript support with type definitions
• 🎨 Physics-based Scrolling - Realistic inertia and friction simulation
• 📦 Zero Configuration - Works out of the box with sensible defaults

📖 Documentation

For more detailed documentation, please visit vue-table-touch-scroll documentation.

📦 Installation

# npm
npm install vue-table-touch-scroll

# pnpm
pnpm add vue-table-touch-scroll

# yarn
yarn add vue-table-touch-scroll

🚀 Quick Start

Global Registration

import { createApp } from 'vue'
import VueTableTouchScroll from 'vue-table-touch-scroll'
import App from './App.vue'

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

Local Registration

<script setup lang="ts">
import { vTableTouchScroll } from 'vue-table-touch-scroll'
</script>

<template>
  <div v-table-touch-scroll class="table-container">
    <table>
      <!-- your table content -->
    </table>
  </div>
</template>

📖 Usage

With UI Library Presets

<template>
  <!-- Element Plus -->
  <div v-table-touch-scroll="{ preset: 'element-plus' }">
    <el-table :data="tableData" height="400">
      <!-- column config -->
    </el-table>
  </div>

  <!-- Ant Design Vue -->
  <div v-table-touch-scroll="{ preset: 'ant-design-vue' }">
    <a-table :data-source="tableData" :scroll="{ x: 1300, y: 400 }" />
  </div>

  <!-- Naive UI -->
  <div v-table-touch-scroll="{ preset: 'naive-ui' }">
    <n-data-table :columns="columns" :data="tableData" :scroll-x="1300" />
  </div>
</template>

Custom Selector

<template>
  <div v-table-touch-scroll="{ selector: '.custom-scroll-container' }">
    <CustomTable />
  </div>
</template>

Full Configuration Example

<script setup lang="ts">
import { ref } from 'vue'
import { type TableTouchScrollOptions, vTableTouchScroll } from 'vue-table-touch-scroll'

const options: TableTouchScrollOptions = {
  preset: 'element-plus',
  dragThreshold: 5,
  friction: 0.95,
  disableInertia: false,
  clickBlockThreshold: 0.5,
  onScrollStart: () => console.log('Scroll started'),
  onScrollEnd: () => console.log('Scroll ended'),
}

const enabled = ref(true)
</script>

<template>
  <div v-table-touch-scroll="enabled ? options : false">
    <el-table :data="tableData" height="400">
      <!-- column config -->
    </el-table>
  </div>
</template>

⚙️ Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable/disable the directive | | preset | TablePreset | - | UI library preset name | | selector | string | - | CSS selector for the target scroll element | | dragThreshold | number | 5 | Movement threshold (px) before scroll direction is determined | | friction | number | 0.95 | Friction/decay rate for inertia scrolling (0.8-0.99) | | disableInertia | boolean | false | Disable inertia scrolling | | clickBlockThreshold | number | 0.5 | Velocity threshold (px/ms) for blocking clicks after fast scrolling | | onScrollStart | () => void | - | Callback when scrolling starts | | onScrollEnd | () => void | - | Callback when scrolling ends |

UI Library Presets

| Preset | UI Library | Scroll Container Selector | |--------|------------|---------------------------| | 'element-plus' | Element Plus | .el-scrollbar__wrap | | 'ant-design-vue' | Ant Design Vue | .ant-table-body | | 'arco-design' | Arco Design | .arco-table-body | | 'naive-ui' | Naive UI | .n-scrollbar-container | | 'primevue' | PrimeVue | .p-datatable-table-container | | 'vuetify' | Vuetify | .v-table__wrapper tbody | | 'vxe-table' | VxeTable | .vxe-table--body-inner-wrapper |

📦 Exports

// Default export: Vue plugin (for global registration)
import VueTableTouchScroll from 'vue-table-touch-scroll'
// Named exports
import {
  vTableTouchScroll,           // Directive
  type TableTouchScrollOptions, // Options type
  type TablePreset,             // Preset type
  UI_LIBRARY_SELECTORS,         // UI library selector mapping
  getSelectorByPreset,          // Get selector by preset
} from 'vue-table-touch-scroll'

🏗️ Development

This project uses a pnpm workspaces monorepo structure.

# Install dependencies
pnpm install

# Run development environment
pnpm dev

# Build all packages
pnpm build

# Run tests
pnpm test

# Type checking
pnpm typecheck

# Lint and format
pnpm lint
pnpm format

📁 Project Structure

vue-table-touch-scroll/
├── packages/
│   ├── core/                    # Core directive implementation
│   ├── utils/                   # Utility functions
│   └── vue-table-touch-scroll/  # Main package entry
├── play/                        # Development playground
├── docs/                        # Documentation site
└── README.md

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

📄 License

MIT License © 2024-Present LostElk

🌟 Why Choose Vue Table Touch Scroll?

• Native-like Experience: Provides a smooth, native-grade scrolling experience on mobile devices
• Zero Dependencies: No external dependencies, keeping your bundle size minimal
• Universal Compatibility: Works with any Vue 3 project and popular UI libraries
• Performance Optimized: Built with performance in mind, using requestAnimationFrame and optimized event handling
• TypeScript Support: Full TypeScript types for better developer experience
• Extensible: Easy to customize and extend with your own scroll container selectors

📞 Support

If you have any questions or issues, please open an issue on GitHub.