Introduction

vue3-mobile-table is a lightweight, high-performance mobile table engine specifically designed for the Vue 3 ecosystem.

It solves two major developer pain points:

  • the scarcity of mature mobile-native table components
  • the subpar user experience when using desktop-oriented components on mobile devices

Through its minimalist directive-based integration, a single line of code is all it takes to empower any PC table component—such as Element Plus or Ant Design Vue—with a native-grade, silky-smooth mobile interaction experience.

Core Features

  • Physics-Based Inertial Engine — Utilizes Delta Time frame-rate normalization to eliminate speed variances across different refresh rates, ensuring a consistent, silky-smooth feel on any Hz screen. Built-in intelligent inertia protection identifies finger pauses to prevent accidental inertial triggers.
  • Gesture Intent & Axis Locking — Millisecond-level intent determination filters diagonal jitter. Operations are locked to a single axis (horizontal or vertical) throughout the gesture, eliminating the "diagonal drift" pain point when browsing long tables.
  • Intelligent Edge Sensing — Automatically detects scroll boundaries. When reaching the edge, control is smoothly handed back to the browser, maintaining full compatibility with system-level native interactions like iOS slide-to-back.
  • Dynamic Braking & Click Protection — Smartly distinguishes between "braking" and "triggering." Click events are intercepted only during high-speed inertia to provide immediate stabilization, preventing accidental clicks while flicking through data.
  • Multi-Touch Tracking & Gesture Adaptation — Locks onto active fingers using Touch ID to eliminate coordinate jumps during finger handover. When multi-touch gestures (e.g., pinch-to-zoom) are detected, the engine enters a silent mode, allowing the browser to handle native behaviors.
  • Deep UI Library Integration — Built-in presets for over ten major UI libraries, including Element Plus, Ant Design Vue, Naive UI, and VxeTable. Achieve deep interaction optimization with just a single line of code.
  • Multi-Mode Device Adaptation (Lazy Hijacking) — An optimized state machine for hybrid devices like Surface and touch-screen laptops. Offers zero-intrusion for pure mouse operations, activating on-demand only for touch inputs to ensure seamless transitions between input methods.
  • Landscape Mode Gesture Calibration — Fully supports CSS transform: rotate() scenarios. Automatically corrects touch trajectories via intelligent axis mapping, ensuring touch directions align perfectly with visual intuition without additional computational overhead.
  • Lightweight & Zero Dependencies — Implemented in pure TypeScript with no third-party package dependencies, ensuring a clean and stable core logic.

What Problems It Solves

The Vue ecosystem still lacks mobile Table solutions that can stand alongside mainstream desktop table stacks. For complex flows such as reporting, mobile also needs high-performance tables with full interaction capabilities, but that gap remains obvious today.

In practice teams usually take one of two paths: build a table in-house, where touch interaction, scrolling mechanics, and advanced features are extremely expensive to implement and maintain; or reuse desktop-oriented stacks such as Element Plus tables, which are not optimized for mobile and often feel wrong on touch and small screens.

When reusing desktop table components on mobile, common pain points include:

  • Diagonal Swipe Accidental Touch — horizontal data scanning unintentionally triggers vertical page scrolling due to imprecise finger paths
  • Unstable Directional Locking — slight finger tilt causes frequent axis switching and a shaky scroll path
  • Sluggish Touch Response — native overflow: auto often lags in deeply nested UI structures
  • Lack of Natural Momentum — scrolling stops too abruptly or feels stiff after release, requiring repeated swipes
  • Visual Header Tearing — fixed headers fail to keep pixel-level sync with body scrolling
  • Inconsistent Cross-Device Haptics — refresh-rate differences produce inconsistent inertia feel across devices
  • Gesture Logic Conflicts — multi-finger coordinate jumps or interference with native gestures such as iOS swipe-back
  • Hybrid Device Interference — aggressive hijacking on Surface/touch laptops can hurt mouse and trackpad users
  • CSS Rotation Coordinate Mismatch — transform: rotate() landscape layouts misalign physical touch direction and logical scroll direction

v-mobile-table addresses these by intercepting touch flow and running an in-directive scroll physics engine; see How It Works for the full breakdown.

How It Works

The directive intercepts touch event flow and runs a complete in-directive scroll physics pipeline, including axis decision, velocity sampling, inertia decay, edge yielding, and hybrid-device strategies for stable mobile behavior.

Read How It Works for the full mechanism breakdown and implementation details.

Use Cases

Data viewing

Complex mobile data views such as wide tables, financial reports, and reconciliation sheets. You need horizontal dragging, vertical browsing, sorting, and nested tables within a small viewport, which demands strong table capabilities, touch feel, and rendering performance.

Cross-platform consistency

The same business screens must work on both desktop and mobile, delivering predictable interaction without rewriting table business logic.

Next Steps

Usage Guide