Usage Guide

This page covers common usage patterns for the v-mobile-table directive. For complete configuration options and type definitions, see API.

Installation

npm
yarn
pnpm
npm install vue3-mobile-table

Global Registration

main.ts
import { createApp } from 'vue'
import App from './App.vue'
import Vue3MobileTable from 'vue3-mobile-table'

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

Local Registration

If you don't need global registration, you can import the directive directly in a component:

<script setup lang="ts">
import { vMobileTable } from 'vue3-mobile-table'
</script>

<template>
  <div v-mobile-table="{ preset: 'element-plus' }">
    <el-table :data="tableData" />
  </div>
</template>

Usage in Templates

MyComponent.vue
<template>
  <div v-mobile-table="{ preset: 'element-plus' }">
    <el-table :data="tableData">
      <el-table-column prop="name" label="Name" />
      <el-table-column prop="age" label="Age" />
      <el-table-column prop="address" label="Address" />
    </el-table>
  </div>
</template>

Using UI Library Presets

For UI libraries with built-in presets, simply pass the preset name — no need to manually find scroll container selectors:

<template>
  <!-- Element Plus -->
  <div v-mobile-table="{ preset: 'element-plus' }">
    <el-table :data="tableData">
      <el-table-column prop="name" label="Name" />
    </el-table>
  </div>

  <!-- Ant Design Vue -->
  <div v-mobile-table="{ preset: 'ant-design-vue' }">
    <a-table :data-source="dataSource" :columns="columns" />
  </div>

  <!-- VxeTable -->
  <div v-mobile-table="{ preset: 'vxe-table' }">
    <vxe-table :data="tableData">
      <vxe-column field="name" title="Name" />
    </vxe-table>
  </div>
</template>

Using Custom Selectors

For UI libraries without built-in presets, use selector to specify the scroll container inside the table:

<template>
  <div v-mobile-table="{ selector: '.my-scroll-container' }">
    <MyTable />
  </div>
</template>

Custom Physics Parameters

Adjust friction and drag threshold based on your use case:

<template>
  <!-- Smoother: high friction (slow decay), low threshold -->
  <div v-mobile-table="{ preset: 'element-plus', friction: 0.98, dragThreshold: 3 }">
    <el-table :data="tableData" />
  </div>

  <!-- More precise: low friction (fast decay), high threshold -->
  <div v-mobile-table="{ preset: 'element-plus', friction: 0.85, dragThreshold: 10 }">
    <el-table :data="tableData" />
  </div>
</template>

Dynamic Control

Pass false to completely disable the directive — all event listeners and style hijacking will be fully cleaned up:

<template>
  <div v-mobile-table="directiveEnabled ? { preset: 'element-plus' } : false">
    <el-table :data="tableData" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const directiveEnabled = ref(true)
</script>

You can also use the enabled property, which has the same effect:

<template>
  <div v-mobile-table="{ enabled: directiveEnabled, preset: 'element-plus' }">
    <el-table :data="tableData" />
  </div>
</template>

Device Detection Mode

By default, the directive uses mode: 'auto' which automatically detects the device type and applies the optimal strategy:

  • Desktop (pure PC): Dormant — no event binding, zero overhead
  • Mobile (phone/tablet): Immediately activate full touch handling
  • Hybrid (Surface / touchscreen laptop): Lazy hijacking — only activates after confirming a real touch drag, avoiding interference with mouse/trackpad users

Use mode: 'always' to force-enable touch handling regardless of device type. This is useful for debugging or when you know the target environment:

<template>
  <div v-mobile-table="{ preset: 'element-plus', mode: 'always' }">
    <el-table :data="tableData" />
  </div>
</template>

Disabling Edge Detection

By default, the directive detects when scrolling reaches the container boundary and hands control back to the browser, enabling native gestures like iOS swipe-back. In fullscreen overlay scenarios (e.g. landscape mode), this is undesirable. Set disableEdgeDetection: true to keep full control:

<template>
  <div v-mobile-table="{ preset: 'element-plus', disableEdgeDetection: true }">
    <el-table :data="tableData" />
  </div>
</template>

CSS Rotation Support

When using CSS transform: rotate() to simulate landscape mode on mobile, the touch coordinate axes no longer align with the element's logical axes. The rotation parameter tells the directive to apply an inverse coordinate transform:

<template>
  <div
    v-mobile-table="{ preset: 'element-plus', rotation: 90 }"
    class="landscape-container"
  >
    <el-table :data="tableData" />
  </div>
</template>

<style scoped>
.landscape-container {
  transform: rotate(90deg);
  transform-origin: top left;
  width: 100vh;
  height: 100vw;
  translate: 100vw 0;
}
</style>

Supported values: 0 (default), 90, -90, 180. For a complete landscape toggle example, see the Landscape Mode guide.

Lifecycle Callbacks

<script setup lang="ts">
const scrollOptions = {
  preset: 'element-plus' as const,
  onScrollStart: () => {
    // Scroll started: close overlays, record start time, etc.
  },
  onScrollEnd: () => {
    // Scroll ended: trigger analytics, load more data, etc.
  },
}
</script>

<template>
  <div v-mobile-table="scrollOptions">
    <el-table :data="tableData" />
  </div>
</template>
Introduction
Options & Types