| name | tdesign-mobile |
| description | TDesign Mobile component libraries for Vue 3 and React — Tencent's mobile H5 component libraries (tdesign-mobile-vue v1.13.x + tdesign-mobile-react v0.22.x, active). Covers mobile-optimized components (Tabbar, NavBar, ActionSheet, SwipeCell, etc.) with responsive sizing, safe-area behavior, and TDesign token parity. |
TDesign Mobile — Vue 3 & React Mobile H5
Sources:
Docs:
1. When to use
- Mobile web / H5 (not MiniProgram — use
tdesign-miniprogram for that)
- Vue 3 or React project targeting mobile browsers
- Want cross-platform design parity with TDesign Desktop
- Need mobile UI that shares brand tokens with a TDesign desktop or MiniProgram product
2. Install
Vue 3
npm install tdesign-mobile-vue
import { createApp } from 'vue';
import TDesignMobile from 'tdesign-mobile-vue';
import 'tdesign-mobile-vue/es/style/index.css';
createApp(App).use(TDesignMobile).mount('#app');
React
npm install tdesign-mobile-react
import 'tdesign-mobile-react/es/style/index.css';
import { Button } from 'tdesign-mobile-react';
Required viewport
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover">
3. Component catalog
Basic: Button · Cell · CellGroup · Tag · Avatar · Image · Grid · Divider
Navigation: NavBar · Tabbar · TabbarItem · Tabs · Steps · Sticky · BackTop
Form: Form · Input · Textarea · Radio · Checkbox · Switch · Stepper · Picker · DateTimePicker · Slider · Rate · Search · Upload · Cascader
Data: Swiper · SwipeCell · Collapse · IndexBar · Rate · Badge · Progress · Skeleton
Feedback: Dialog · ActionSheet · Popup · Toast · Message · Notify · Loading · PullDownRefresh
Full catalog: https://tdesign.tencent.com/mobile-vue/components/button
4. Usage (Vue 3)
Button
<template>
<t-button theme="primary" @click="save">保存</t-button>
<t-button theme="primary" shape="round" block>Block CTA</t-button>
<t-button theme="danger" variant="outline">删除</t-button>
</template>
Cell list
<template>
<t-cell-group title="设置">
<t-cell title="个人资料" arrow @click="goProfile" />
<t-cell title="通知" note="开启">
<template #rightIcon>
<t-switch v-model="notif" />
</template>
</t-cell>
<t-cell title="注销" arrow theme="danger" @click="logout" />
</t-cell-group>
</template>
Tabbar (bottom nav)
<template>
<t-tabbar v-model="active" fixed safe-area-inset-bottom>
<t-tabbar-item icon="home" value="home">首页</t-tabbar-item>
<t-tabbar-item icon="discover" value="discover">发现</t-tabbar-item>
<t-tabbar-item icon="app" value="app">应用</t-tabbar-item>
<t-tabbar-item icon="user" value="user">我的</t-tabbar-item>
</t-tabbar>
</template>
Swipe cell (swipe-to-reveal)
<template>
<t-swipe-cell>
<t-cell title="项目 A" />
<template #right>
<t-button theme="danger" shape="square">删除</t-button>
</template>
</t-swipe-cell>
</template>
Picker
<template>
<t-picker
v-model:value="selected"
:columns="[[{label: '北京', value: 'bj'}, {label: '上海', value: 'sh'}]]"
title="选择城市"
confirm-btn="确认"
cancel-btn="取消"
/>
</template>
Usage (React) — Button
import { Button } from 'tdesign-mobile-react';
<Button theme="primary" onClick={save}>保存</Button>
<Button theme="primary" shape="round" block>Block CTA</Button>
5. Theme (CSS variables)
:root {
--td-brand-color: #0052d9;
--td-brand-color-disabled: #b5c7ff;
--td-font-size-m: 14px;
--td-radius-default: 6px;
--td-safe-area-bottom: env(safe-area-inset-bottom);
}
Keep mobile tokens aligned with desktop TDesign:
- Map the same
--td-brand-color-* scale where the package exposes it.
- Preserve state tokens for hover/active/disabled even when mobile has fewer hover interactions.
- Use
env(safe-area-inset-bottom) for fixed bottom UI and test on devices with a home indicator.
6. BANNED
- ❌ NEVER use the desktop
tdesign-vue-next for mobile — layouts don't adapt to narrow screens. Use tdesign-mobile-vue.
- ❌ NEVER skip the
<meta viewport> tag
- ❌ NEVER hardcode
px for font sizes — use vw / rem with scaling or use TDesign's tokens
- ❌ NEVER omit
safe-area-inset-bottom on <Tabbar fixed> — iOS home-indicator overlap
- ❌ NEVER nest
<Swiper> inside a scroll container without touch-action config
- ❌ NEVER use React mobile + Vue mobile in the same project
- ❌ NEVER style components with high-specificity selectors — override CSS variables
- ❌ NEVER reuse desktop density unchanged on mobile — adjust hit targets, spacing, and safe areas
7. Pre-flight checklist
- [ ] Chose the right package: mobile-vue for Vue, mobile-react for React
- [ ] Viewport meta tag set
- [ ] safe-area-inset applied to fixed-bottom components
- [ ] Using mobile variants (not desktop)
- [ ] Tested on physical device at common widths (375px, 390px, 414px)
- [ ] Brand color overridden if not Tencent-blue
- [ ] Token scale is aligned with desktop / MiniProgram TDesign if this is a cross-platform product
- [ ] Tabbar items have fixed icons (not dynamic emoji)
- [ ] Pull-to-refresh / infinite-scroll tested on real touch
8. Dial fit
formality: 5 · motion: 5 · density: 4 · warmth: 5 · contrast: 6
