varlet Documentation

File: README.md Copy Chapter

Intro Copy Section

Varlet is a Vue3 component library based on Material Design 2 and 3, supporting mobile and desktop, developed and maintained by varletjs organization.

Features Copy Section

• 🚀   Provide 70+ high quality general purpose components
• 🚀   Components are very lightweight
• 💪   Developed by Chinese, complete Chinese and English documentation and logistics support
• 🛠️   Support on-demand introduction
• 🛠️   Support theme customization
• 🌍   Support internationalization
• 💡   Support WebStorm syntax highlighting
• 💪   Support the SSR
• 📦   Support Nuxt Module
• 💡   Support the Typescript
• 💪   Make sure more than 90 percent unit test coverage, providing stability assurance
• 🎨   Supports both Material Design 2 and Material Design 3 design systems
• 🛠️   Support dark mode
• 🔧   Provide official VSCode extension
• ⌨️   Support Accessibility (still improving)

Install Copy Section

CDN Copy Section

varlet.js contain all the styles and logic of the component library, and you can import them.

<script src="https://cdn.jsdelivr.net/npm/vue"></script>
 
<script src="https://cdn.jsdelivr.net/npm/@varlet/touch-emulator/iife.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@varlet/ui/umd/varlet.js"></script>
<script>
  const app = Vue.createApp({
    template: '<var-button>Button</var-button>'
  })
  app.use(Varlet).mount('#app')
</script>

Webpack / Vite Copy Section

# Install with npm or yarn or pnpm

# npm
npm i @varlet/ui -S

# yarn
yarn add @varlet/ui

# pnpm
pnpm add @varlet/ui

import App from './App.vue'
import Varlet from '@varlet/ui'
import { createApp } from 'vue'
import '@varlet/ui/es/style'

createApp(App).use(Varlet).mount('#app')

Official Ecosystem Copy Section

The following projects are maintained by the official team for a long time.

Community Ecosystem Copy Section

The following projects are maintained by community personnel, welcome to add.

Playground Copy Section

See Varlet UI Playground.

Contribution Copy Section

See Contributing Guide.

GitCode Repo Copy Section

See Here.

Thanks to contributors Copy Section

Thanks to the following sponsors Copy Section

Sponsor this project Copy Section

Sponsor this project to support our better creation.

Wechat / Alipay

File: packages/varlet-vscode-extension/README.md Copy Chapter

Varlet VSCode Extension

English | 中文

Intro Copy Section

For a better development experience, we built a VSCode plugin.

Features Copy Section

• 🛠️  Support syntax hints and quick completion for all components.
• 🛠️  Support document address preview and quick jump for all components.
• 🛠️  Support frame selection of code snippets to quickly open Playground.
• 🛠️  Support full icon preview for icon components.
• 🌍  Support switching between Chinese and English.

Install Copy Section

VsCode Extension Marketplace Search varlet-vscode-extension.

How To Use Copy Section

Grammatical hints appear when you enter the keyword of the component name, and you can quickly complete it after selecting it.

Moving the mouse to the component name will display the document address of the component, which can be clicked to jump.

Press space or attribute keywords in the attribute input range of the label to display attribute completion prompts and attribute information.

When the name property of the Icon component is input, an icon preview will appear, and syntax completion will be performed after selection.

Frame the code snippet, and you can quickly open Playground in the right-click menu to preview the framed code online.

Support switching between Chinese and English, more friendly to Chinese people.

File: packages/varlet-vscode-extension/README.zh-CN.md Copy Chapter

Varlet VSCode Extension

English | 中文

介绍 Copy Section

为了更优秀的开发体验，我们构建了一个 VSCode 插件。

特性 Copy Section

• 🛠️  支持全组件的语法提示、快速补全。
• 🛠️  支持全组件的文档地址预览、快速跳转。
• 🛠️  支持框选代码片段，快速打开 Playground。
• 🛠️  支持图标组件的全图标预览。
• 🌍  支持中英文切换。

安装 Copy Section

VsCode 插件市场搜索 varlet-vscode-extension。

如何使用 Copy Section

输入组件名称关键字时出现语法提示，选中后进行快速补全。

鼠标移动到组件名会显示组件的文档地址，可以点击进行跳转。

在标签的属性输入范围按下空格或属性关键字，显示属性补全提示和属性信息。

输入 Icon 组件的 name 属性时出现图标预览，选中后进行语法补全。

框选代码片段，右键菜单中可以快速打开 Playground 对框选的代码进行线上预览。

支持中英文切换，对中国人更加友好。

File: packages/varlet-ui-playground/src/download/template/README.md Copy Chapter

Varlet Playground Demo

To start:

npm install
npm run dev

# if using yarn:
yarn
yarn dev

File: packages/varlet-ui/docs/atomicCssSupport.en-US.md Copy Chapter

Atomic CSS support

Intro Copy Section

We've provided common CSS atomization framework presets, made it easier to access the component library's underlying style variables, and standardized page responsiveness breakpoints.

UnoCSS Copy Section

Install

# playground-ignore
# npm
npm i @varlet/preset-unocss -D
# yarn
yarn add @varlet/preset-unocss -D
# pnpm
pnpm add @varlet/preset-unocss -D

Configuration

// playground-ignore
// uno.config.ts
import { defineConfig, presetUno } from 'unocss'
import { presetVarlet } from '@varlet/preset-unocss'

export default defineConfig({
  presets: [presetUno(), presetVarlet()]
})

More Options

Presets detailed definition please watch here.

Tailwindcss Copy Section

Install

# playground-ignore
# npm
npm i @varlet/preset-tailwindcss -D
# yarn
yarn add @varlet/preset-tailwindcss -D
# pnpm
pnpm add @varlet/preset-tailwindcss -D

Tailwindcss V3 Configuration

// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
  ],
  presets: [presetVarlet()]
}

Tailwindcss V4 Configuration

// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  presets: [presetVarlet()]
}

/** src/style.css */
@import "tailwindcss";
@config "../tailwind.config.js";

More Options Copy Section

Presets detailed definition please watch here.

Usage Copy Section

<template>
  hello
  world
  varlet
</template>

We also support the HSL variables, which makes the transparency of adjusting the color easier.

<template>
  hello
</template>

File: packages/varlet-ui/docs/atomicCssSupport.zh-CN.md Copy Chapter

原子化 CSS 支持

介绍 Copy Section

我们提供了常见的 CSS 原子化框架预设，使访问组件库的基础样式变量更加容易，并且一致化了页面响应式断点。

UnoCSS Copy Section

安装

# playground-ignore
# npm
npm i @varlet/preset-unocss -D
# yarn
yarn add @varlet/preset-unocss -D
# pnpm
pnpm add @varlet/preset-unocss -D

配置

// playground-ignore
// uno.config.ts
import { defineConfig, presetUno } from 'unocss'
import { presetVarlet } from '@varlet/preset-unocss'

export default defineConfig({
  presets: [presetUno(), presetVarlet()]
})

更多配置

预设的详细定义请看这里。

Tailwindcss Copy Section

安装

# playground-ignore
# npm
npm i @varlet/preset-tailwindcss -D
# yarn
yarn add @varlet/preset-tailwindcss -D
# pnpm
pnpm add @varlet/preset-tailwindcss -D

Tailwindcss V3 配置

// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  content: [
    './index.html',
    './src/**/*.{vue,js,ts,jsx,tsx}',
  ],
  presets: [presetVarlet()]
}

Tailwindcss V4 配置

// playground-ignore
// tailwind.config.js
import { presetVarlet } from '@varlet/preset-tailwindcss'

export default {
  presets: [presetVarlet()]
}

/** src/style.css */
@import "tailwindcss";
@config "../tailwind.config.js";

更多配置

预设的详细定义请看这里。

使用方式 Copy Section

<template>
  hello
  world
  varlet
</template>

我们同时也支持了 hsl 变量，这使得调整颜色的透明度变得更加容易。

<template>
  hello
</template>

File: packages/varlet-ui/docs/browserAdaptation.en-US.md Copy Chapter

Browser Adaptation

Intro Copy Section

The component library provides mobile and desktop adaptations,
scheme varlet-touch-emulator is used for mobile terminal adaptation,
scheme varlet-touch-emulator is used for mobile terminal adaptation.

Mobile Adaptation Copy Section

CSS Unit Adaptation

The component library design is based on the 375px width design draft.
It is recommended to use postcss-px-to-viewport to convert px units into vw units to achieve mobile terminal adaptation.
Create postcss.config.js under the Webpack/Vite project root path And do the following configuration 375px -> 100vw.

# playground-ignore
# npm
npm i postcss-px-to-viewport -D

# yarn
yarn add postcss-px-to-viewport -D

# pnpm
pnpm add postcss-px-to-viewport -D

// playground-ignore
// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
      unitPrecision: 6,
      unitToConvert: 'px',
      viewportUnit: 'vmin',
      fontViewportUnit: 'vmin',
      propList: ['*'],
    }
  }
}

Theme Unit Adaptation (Viewport)

Because the theme is mounted at runtime and is not affected by postcss, the component library provides a utility tool Themes.toViewport for adaptation. The theme returned by the function will use the 375px -> 100vmin rule by default.

import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark)

You can also make changes to the conversion rules

import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark, {
  // defaults 375
  viewportWidth: 750,
  // defaults 'vmin'
  viewportUnit: 'vw',
  // defaults 6
  unitPrecision: 4,
})

Theme Unit Adaptation (Rem)

Similar to the Viewport solution

import { Themes } from '@varlet/ui'

const remTheme = Themes.toRem(Themes.md3Dark)

Or customize

import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toRem(Themes.md3Dark, {
  // defaults 16
  rootFontSize: 32,
  // defaults 6
  unitPrecision: 4,
})

Desktop Adaptation Copy Section

Because component library interaction events are developed using touch events, mouse events on the desktop side are not supported.
It is recommended to use @varlet/touch-emulator to set touch -> mouse for desktop adaptation.

# playground-ignore
# npm
npm i @varlet/touch-emulator
# yarn
yarn add @varlet/touch-emulator
# pnpm
pnpm add @varlet/touch-emulator

// playground-ignore
import '@varlet/touch-emulator'

File: packages/varlet-ui/docs/browserAdaptation.zh-CN.md Copy Chapter

浏览器适配

介绍 Copy Section

组件库提供移动端和桌面端适配方案，
移动端使用 postcss-px-to-viewport 方案进行适配，
桌面端使用 @varlet/touch-emulator 方案进行适配。

移动端适配 Copy Section

CSS 单位适配

组件库设计基于 375px 宽度设计稿，推荐使用 postcss 插件将 px 单位转换成 vmin 单位从而实现移动端适配。
在 webpack/vite 项目根路径下创建 postcss.config.js 并做如下配置之后 375px -> 100vmin。

# playground-ignore
# npm
npm i postcss-px-to-viewport -D

# yarn
yarn add postcss-px-to-viewport -D

# pnpm
pnpm add postcss-px-to-viewport -D

// playground-ignore
// postcss.config.js
module.exports = {
  plugins: {
    'postcss-px-to-viewport': {
      viewportWidth: 375,
      unitPrecision: 6,
      unitToConvert: 'px',
      viewportUnit: 'vmin',
      fontViewportUnit: 'vmin',
      propList: ['*'],
    }
  }
}

主题包单位适配 (Viewport)

因为主题包是运行时挂载的，不受 postcss 影响，组件库提供了实用工具 Themes.toViewport 进行适配，函数返回的主题将默认使用 375px -> 100vmin 的规则。

import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark)

也可以对转换规则进行更改

import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toViewport(Themes.md3Dark, {
  // 默认值为 375
  viewportWidth: 750,
  // 默认值为 'vmin'
  viewportUnit: 'vw',
  // 默认值为 6
  unitPrecision: 4,
})

主题包单位适配 (Rem)

与 Viewport 方案类似

import { Themes } from '@varlet/ui'

const remTheme = Themes.toRem(Themes.md3Dark)

也支持自定义

import { Themes } from '@varlet/ui'

const viewportTheme = Themes.toRem(Themes.md3Dark, {
  // 默认值为 16
  rootFontSize: 32,
  // 默认值为 6
  unitPrecision: 4,
})

桌面端适配 Copy Section

由于组件库交互事件使用 touch 事件进行开发，不支持桌面端的 mouse 事件，
推荐使用 @varlet/touch-emulator 将 touch -> mouse 从而实现桌面端适配。

# playground-ignore
# npm
npm i @varlet/touch-emulator
# yarn
yarn add @varlet/touch-emulator
# pnpm
pnpm add @varlet/touch-emulator

// playground-ignore
import '@varlet/touch-emulator'

File: packages/varlet-ui/docs/cli.en-US.md Copy Chapter

Components Library Tools

Intro Copy Section

The out-of-the-box Vue3 component library rapid prototyping tool provides a series of commands and tools to solve the problem of component library development.

Features Copy Section

• 📦  Out-of-the-box component library development environment
• 📦  An out-of-the-box component library compilation tool that supports exporting esm, cjs, umd module codes
• 🛠️  Configuration file-based component library documentation site, support Baidu statistics and theme customization
• 🛠️  Supports both sfc and tsx styles for writing component libraries
• 📦  Out-of-the-box code inspection tool
• 📦  Out-of-the-box unit testing tools
• 📦  Out-of-the-box code publishing tool, publishes to both npm and github, and automatically generates changelogs
• 💪  Support for VSCode extension development
• 💪  Support build svg to web fonts
• 💪  Support for Typescript
• 💪  Support Various themes, including Material Design 2, Material Design 3
• 🌍  Support Internationalization
• 🚀  Based on pnpm

Recommended toolchain Copy Section

Under Varlet’s current component-library toolchain, we recommend combining @varlet/cli, vite-plus (vp), and rattail (rt): @varlet/cli covers first-party library workflows (docs, compile, tests, …), vp covers lint/format and app/extension build entrypoints aligned with the Oxc/Rolldown stack, and rattail covers clean, git hooks, changelog, release, commit-lint, and similar automation. Use this trio for new libraries and scaffold upgrades.

Commands pending deprecation Copy Section

These commands still run for backward compatibility and may print a deprecation notice. Do not rely on them in new scripts or new projects — prefer vp / rt (or vr where documented). Any future changes will be called out in release notes.

Quickstart Copy Section

@varlet/cli has built-in sfc and tsx style component library project templates, which can be generated directly by the gen command.
It is convenient for you to directly enter the component library development.

# playground-ignore
pnpm add @varlet/cli -g
varlet-cli gen

Advanced customization Copy Chapter

Configuration file Copy Section

The varlet.config.mjs in the project root directory is used to manage the specific details of the entire component library project.
The default configuration can be viewed varlet.default.config.ts.
Also refer to @varlet/ui varlet.config.mjs.

Menu

Custom pages Copy Section

If you want to insert other pages into the component library, you can create a pages folder in the project root directory to write a vue component to generate other pages.
The directory structure is as follows:

// playground-ignore
|-- varlet-ui
  |-- src
  |-- docs
  |-- pages
    |-- sponsor
      |-- index.vue
    |-- contributor
      |-- locale
        |-- en-US.ts
      |-- index.vue
    |-- changelog
      |-- locale
        |-- zh-CN.ts
        |-- en-US.ts
      |-- index.vue

The resulting route is as follows:

// playground-ignore
/zh-CN/sponsor
/en-US/contributor
/zh-CN/changelog
/en-US/changelog

Command related Copy Section

Start the development server

# playground-ignore
varlet-cli dev
# force mode
varlet-cli dev -f
# draft mode
varlet-cli dev -d

Build a documentation site

# playground-ignore
varlet-cli build

Preview documentation site

# playground-ignore
varlet-cli preview

Compile component library

# playground-ignore
varlet-cli compile

Compile style vars types declaration file

# playground-ignore
varlet-cli compile:style-vars

Build svg to web fonts

# playground-ignore
varlet-cli build:icons -w
varlet-cli build:icons

Execute all unit tests

# playground-ignore
varlet-cli test

Execute a unit test

# playground-ignore
varlet-cli test -c <componentName>

Execute unit tests in watch mode

# playground-ignore
varlet-cli test -w

Execute unit tests and report coverage

# playground-ignore
varlet-cli test -cov

Generate a project template

# playground-ignore
varlet-cli gen

# Options
-n
--name
  project name
-s
--sfc
  Generate sfc-style project templates
-t
--tsx
  Generate tsx-style project templates
-l
--locale
  Need to support internationalization

Create a component template file

# playground-ignore
varlet-cli create

# Options
-n
--name
  project name
-s
--sfc
  Generate sfc-style component
-t
--tsx
  Generate tsx-style component
-l
--locale
  Need to support internationalization

Note before publish Copy Section

1. npm repository registry must set to npm official mirror
2. Execute npm login to log in

Q & A Copy Section

How to solve failure of installing sharp ?

• You can choose to change mirror site which contains binaries for both sharp and libvips.

pnpm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
pnpm config set sharp_libvips_binary_host "https://npmmirror.com/mirrors/sharp-libvips"

File: packages/varlet-ui/docs/cli.zh-CN.md Copy Chapter

组件库快速成型工具

介绍 Copy Section

开箱即用的 Vue3组件库 快速成型工具，提供了一系列命令和工具去解决组件库开发上的问题。

特性 Copy Section

• 📦  开箱即用的组件库开发环境
• 📦  开箱即用的组件库编译工具，支持导出 esm, cjs, umd 三种模块代码
• 🛠️  基于配置文件的组件库文档站点，支持百度统计和主题定制
• 🛠️  支持 sfc 和 tsx 两种风格的组件库编写风格
• 📦  开箱即用的代码检查工具
• 📦  开箱即用的单元测试工具
• 📦  开箱即用的代码发布工具,同时发布到 npm 和 github, 并自动生成更新日志
• 💪  支持 VSCode 插件开发
• 💪  支持 字体图标打包
• 💪  支持 Typescript
• 💪  支持 多种主题, 包含 Material Design 2、Material Design 3
• 🌍  支持 国际化
• 🚀  基于 pnpm

推荐技术栈 Copy Section

在全新的 Varlet 组件库工具链 体系下，我们建议将 @varlet/cli、vite-plus（vp）与 rattail（rt）组合使用：前者覆盖组件库文档站与编译等一等能力，后两者承接与 Oxc / Rolldown 栈一致的 lint、format、打包入口，以及 clean、git hooks、changelog、release、commit-lint 等工程自动化。无论是从零搭建新库，还是升级旧脚手架、需要与模板对齐时，都推荐沿用这一组合。

以下命令即将废弃 Copy Section

以下命令仍可执行（会给出废弃相关提示），但不应在新脚本或新工程中再依赖，请优先改用 vp / rt（或文档中的 vr）。具体时间表以后续发布说明为准。

快速开始 Copy Section

@varlet/cli 内置了 sfc 和 tsx 两种风格的组件库项目模板，可以通过 gen 命令直接生成。
方便您直接进入组件库开发。

# playground-ignore
pnpm add @varlet/cli -g
varlet-cli gen

高级定制 Copy Chapter

配置文件 Copy Section

项目根目录下的 varlet.config.mjs 用来管理整个组件库项目的具体细节。
默认配置可查阅 varlet.default.config.ts。
也可以参考 @varlet/ui 的 varlet.config.mjs。

Menu

自定义页面 Copy Section

如果想在组件库中插入其他页面，可以在项目根目录下的创建 pages 文件夹编写 vue 组件， 用来生成其他的页面。
目录结构如下：

// playground-ignore
|-- varlet-ui
  |-- src
  |-- docs
  |-- pages
    |-- sponsor
      |-- index.vue
    |-- contributor
      |-- locale
        |-- en-US.ts
      |-- index.vue
    |-- changelog
      |-- locale
        |-- zh-CN.ts
        |-- en-US.ts
      |-- index.vue

生成的路由如下：

// playground-ignore
/zh-CN/sponsor
/en-US/contributor
/zh-CN/changelog
/en-US/changelog

命令相关 Copy Section

启动开发服务器

# playground-ignore
varlet-cli dev
# force mode
varlet-cli dev -f
# draft mode
varlet-cli dev -d

构建文档站点

# playground-ignore
varlet-cli build

预览文档站点

# playground-ignore
varlet-cli preview

构建组件库

# playground-ignore
varlet-cli compile

构建样式变量类型声明文件

# playground-ignore
varlet-cli compile:style-vars

打包字体图标

# playground-ignore
varlet-cli build:icons -w
varlet-cli build:icons

执行所有的单元测试

# playground-ignore
varlet-cli test

执行单个组件的单元测试

# playground-ignore
varlet-cli test -c <componentName>

以 watch 模式执行单元测试

# playground-ignore
varlet-cli test -w

执行所有的单元测试并报告覆盖率

# playground-ignore
varlet-cli test -cov

生成一个项目模板

# playground-ignore
varlet-cli gen

# Options
-n
--name
  项目名
-s
--sfc
  生成 sfc 风格的项目模板
-t
--tsx
  生成 tsx 格式项目
-l
--locale
  需要支持国际化

创建组件模板文件

# playground-ignore
varlet-cli create

# Options
-n
--name
  组件名
-s
--sfc
  生成 sfc 风格的组件
-t
--tsx
  生成 tsx 风格的文件
-l
--locale
  需要支持国际化

发布前注意 Copy Section

1. npm 的仓库源必须指向 npm 官方镜像
2. 执行 npm login 进行登录

问答 Copy Section

如何解决安装 sharp 失败的问题 ?

• 您可以选择更改包含 sharp 和 libvips 二进制文件的镜像站点

pnpm config set sharp_binary_host "https://npmmirror.com/mirrors/sharp"
pnpm config set sharp_libvips_binary_host "https://npmmirror.com/mirrors/sharp-libvips"