File: README.md
Naive UI
Documentation
Community
DingTalk Group 1 (Member limit reached) 33482509
DingTalk Group 2 (Member limit reached) 35886835
DingTalk Group 3 (Member limit reached) 32377370
DingTalk Group 4 (Member limit reached) 8165002788
DingTalk Group 5 (Member limit reached) 31205022250
DingTalk Group 6 (Member limit reached) 62720001971
DingTalk Group 7 172000005810
Features
Fairly Complete
There are more than 90 components. Hope they can help you write less code.
What's more, they are all treeshakable.
Theme Customizable
We provide an advanced type safe theme system built using TypeScript. All you need is to provide a theme overrides object in JS. Then all the stuff will be done by us.
What's more, no less/sass/css variables, no webpack loaders are required.
Uses TypeScript
All the stuff in Naive UI is written in TypeScript. It can work with your typescript project seamlessly.
What's more, you don't need to import any CSS to use the components.
Fast
I try to make it not rather slow. All data components works with virtual list by default.
What's more, ..., no more. Just enjoy it.
Installation
npm
Use npm to install.
npm i naive-uiFonts
npm i vfontsIcons
Naive UI recommends using xicons as icon library.
Design Resources
Contributing
Please see CONTRIBUTING.md.
License
Naive UI is licensed under the MIT license.
Graphics resources of result component is licensed under the CC-BY 4.0. The graphics resources come from Twemoji.
File: demo/pages/docs/vitepress/zhCN/index.md
Vitepress
注意
本文档涉及到 SSR，请先了解SSR 的注意事项。
例子
这是一个使用 naive-ui、vitepress 的样例，支持 SSR。
你可以直接使用这个样例。
从零开始的关键步骤
如果你希望从头开始改造一个 vitepress 项目，遵循下列步骤
0. 安装 `@css-render/vue3-ssr`
确保其版本 >=0.15.14。
# npm
npm install --save-dev @css-render/vue3-ssr
# pnpm
pnpm install --save-dev @css-render/vue3-ssr1. 把下面的内容增加到 `.vitepress/theme/index.js`
// .vitepress/theme/index.js
import { setup } from '@css-render/vue3-ssr'
import { NConfigProvider } from 'naive-ui'
import { useRoute } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { defineComponent, h, inject } from 'vue'
const { Layout } = DefaultTheme
const CssRenderStyle = defineComponent({
setup() {
const collect = inject('css-render-collect')
return {
style: collect()
}
},
render() {
return h('css-render-style', {
innerHTML: this.style
})
}
})
const VitepressPath = defineComponent({
setup() {
const route = useRoute()
return () => {
return h('vitepress-path', null, [route.path])
}
}
})
const NaiveUIProvider = defineComponent({
render() {
return h(
NConfigProvider,
{ abstract: true, inlineThemeDisabled: true },
{
default: () => [
h(Layout, null, { default: this.$slots.default?.() }),
import.meta.env.SSR ? [h(CssRenderStyle), h(VitepressPath)] : null
]
}
)
}
})
export default {
extends: DefaultTheme,
Layout: NaiveUIProvider,
enhanceApp: ({ app }) => {
if (import.meta.env.SSR) {
const { collect } = setup(app)
app.provide('css-render-collect', collect)
}
}
}2. 把下面的内容增加到 `.vitepress/config.mts`
import { defineConfig } from 'vitepress'
const fileAndStyles: Record<string, string> = {}
export default defineConfig({
// ...
vite: {
ssr: {
noExternal: ['naive-ui', 'date-fns', 'vueuc']
}
},
postRender(context) {
const styleRegex = /<css-render-style>((.|\s)+)<\/css-render-style>/
const vitepressPathRegex = /<vitepress-path>(.+)<\/vitepress-path>/
const style = styleRegex.exec(context.content)?.[1]
const vitepressPath = vitepressPathRegex.exec(context.content)?.[1]
if (vitepressPath && style) {
fileAndStyles[vitepressPath] = style
}
context.content = context.content.replace(styleRegex, '')
context.content = context.content.replace(vitepressPathRegex, '')
},
transformHtml(code, id) {
const html = id.split('/').pop()
if (!html)
return
const style = fileAndStyles[`/${html}`]
if (style) {
return code.replace(/<\/head>/, `${style}</head>`)
}
}
})3. 在 markdown 文件中开始使用 naive-ui
...
<script setup>
import { NButton } from 'naive-ui'
</script>
<NButton>Hello World</NButton>
...File: demo/pages/docs/vitepress/enUS/index.md
Vitepress
Caveat
This document pertains to SSR (Server-Side Rendering). Please familiarize yourself with the SSR Caveats before proceeding.
Example
This is a demo for using naive-ui in vitepress with SSR enabled.
You can directly use the demo.
Key process from scratch
If you want to build your own demo from scratch, follow the next steps:
0. Install `@css-render/vue3-ssr`
Make sure its version >=0.15.14.
# npm
npm install --save-dev @css-render/vue3-ssr
# pnpm
pnpm install --save-dev @css-render/vue3-ssr1. Add this content to `.vitepress/theme/index.js`
// .vitepress/theme/index.js
import { setup } from '@css-render/vue3-ssr'
import { NConfigProvider } from 'naive-ui'
import { useRoute } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { defineComponent, h, inject } from 'vue'
const { Layout } = DefaultTheme
const CssRenderStyle = defineComponent({
setup() {
const collect = inject('css-render-collect')
return {
style: collect()
}
},
render() {
return h('css-render-style', {
innerHTML: this.style
})
}
})
const VitepressPath = defineComponent({
setup() {
const route = useRoute()
return () => {
return h('vitepress-path', null, [route.path])
}
}
})
const NaiveUIProvider = defineComponent({
render() {
return h(
NConfigProvider,
{ abstract: true, inlineThemeDisabled: true },
{
default: () => [
h(Layout, null, { default: this.$slots.default?.() }),
import.meta.env.SSR ? [h(CssRenderStyle), h(VitepressPath)] : null
]
}
)
}
})
export default {
extends: DefaultTheme,
Layout: NaiveUIProvider,
enhanceApp: ({ app }) => {
if (import.meta.env.SSR) {
const { collect } = setup(app)
app.provide('css-render-collect', collect)
}
}
}2. Add this content to `.vitepress/config.mts`
import { defineConfig } from 'vitepress'
const fileAndStyles: Record<string, string> = {}
export default defineConfig({
// ...
vite: {
ssr: {
noExternal: ['naive-ui', 'date-fns', 'vueuc']
}
},
postRender(context) {
const styleRegex = /<css-render-style>((.|\s)+)<\/css-render-style>/
const vitepressPathRegex = /<vitepress-path>(.+)<\/vitepress-path>/
const style = styleRegex.exec(context.content)?.[1]
const vitepressPath = vitepressPathRegex.exec(context.content)?.[1]
if (vitepressPath && style) {
fileAndStyles[vitepressPath] = style
}
context.content = context.content.replace(styleRegex, '')
context.content = context.content.replace(vitepressPathRegex, '')
},
transformHtml(code, id) {
const html = id.split('/').pop()
if (!html)
return
const style = fileAndStyles[`/${html}`]
if (style) {
return code.replace(/<\/head>/, `${style}</head>`)
}
}
})3. Start using naive-ui in your markdown file
...
<script setup>
import { NButton } from 'naive-ui'
</script>
<NButton>Hello World</NButton>
...File: demo/pages/docs/vite-ssge/zhCN/index.md
Vite SSG/SSE
注意
本文档涉及到 SSR，请先了解SSR 的注意事项。
配置指南
如果你正在使用 vite-sse 或者 vite-ssg，通过下面的步骤设定 naive-ui。
1. 安装 `naive-ui`、`@css-render/vue3-ssr`
# pnpm
pnpm i naive-ui @css-render/vue3-ssr
# npm
npm i naive-ui @css-render/vue3-ssr2. 修改 `vite.config.ts`
增加下列内容，如果已经存在一些内容，则合并他们。
import { setup } from '@css-render/vue3-ssr'
defineConfig({
ssr: {
noExternal: ['naive-ui', 'vueuc', 'date-fns']
},
ssgOptions: {
async onBeforePageRender(_, __, appCtx) {
const { collect } = setup(appCtx.app)
;(appCtx as any).__collectStyle = collect
return undefined
},
async onPageRendered(_, renderedHTML, appCtx) {
return renderedHTML.replace(
/<\/head>/,
`${(appCtx as any).__collectStyle()}</head>`
)
}
}
})现在你可以在 vite-ssg 或 vite-sse 项目中使用 naive-ui 了。
File: demo/pages/docs/vite-ssge/enUS/index.md
Vite SSG/SSE
Caveat
This document pertains to SSR (Server-Side Rendering). Please familiarize yourself with the SSR Caveats before proceeding.
Setup Guide
If you are using vite-sse or vite-ssg. Follow the following steps to setup naive-ui.
1. Install `naive-ui`, `@css-render/vue3-ssr`
# pnpm
pnpm i naive-ui @css-render/vue3-ssr
# npm
npm i naive-ui @css-render/vue3-ssr2. Modify `vite.config.ts`
Add following content. If there exists content already, merge them.
import { setup } from '@css-render/vue3-ssr'
defineConfig({
ssr: {
noExternal: ['naive-ui', 'vueuc', 'date-fns']
},
ssgOptions: {
async onBeforePageRender(_, __, appCtx) {
const { collect } = setup(appCtx.app)
;(appCtx as any).__collectStyle = collect
return undefined
},
async onPageRendered(_, renderedHTML, appCtx) {
return renderedHTML.replace(
/<\/head>/,
`${(appCtx as any).__collectStyle()}</head>`
)
}
}
})Then you can using naive-ui in vite-ssg or vite-sse project.
File: demo/pages/docs/usage-sfc/zhCN/index.md
在 SFC 中使用
如果你想使用单文件组件风格（SFC - Single File Component），可以选择直接引入或全局安装在 Vue App 中。
直接引入（推荐）
你可以直接导入组件并使用它。这种情况下，只有导入的组件才会被打包。
如果你想知道如何按需引入主题和语言包，请参考按需引入。
<template>
<n-button>naive-ui</n-button>
</template>
<script>
import { defineComponent } from 'vue'
import { NButton } from 'naive-ui'
export default defineComponent({
components: {
NButton
}
})
</script>如果你可以使用 setup script，你可以用下面的方式使用组件。
<template>
<n-button>naive-ui</n-button>
</template>
<script setup>
import { NButton } from 'naive-ui'
</script>全局安装（不推荐）
安装全部组件
失去 tree-shaking 的能力，打包有冗余代码。
如果你想全局安装但是不想安装全部组件，请参考按需引入。
import naive from 'naive-ui'
import { createApp } from 'vue'
const app = createApp(App)
app.use(naive)安装后，你可以这样在 SFC 中使用全部组件。
<template>
<n-button>naive-ui</n-button>
</template>Volar 支持（2.24.2）
如果你在使用 Volar，那么可以在 tsconfig.json 中配置 compilerOptions.types 来指定全局组件类型。
// tsconfig.json
{
"compilerOptions": {
// ...
"types": ["naive-ui/volar"]
}
}File: demo/pages/docs/usage-sfc/enUS/index.md
Usage in SFC
If you want to use the Single File Component(SFC) style, you can directly import components from Naive UI or install it globally to a Vue app.
Import Directly (Recommended)
You can import a component directly and use it. In this form, only components imported will be bundled.
If you want to know how to import themes and locales, please see Import on Demand.
<template>
<n-button>naive-ui</n-button>
</template>
<script>
import { defineComponent } from 'vue'
import { NButton } from 'naive-ui'
export default defineComponent({
components: {
NButton
}
})
</script>If you can use vue setup script, you can use it like this.
<template>
<n-button>naive-ui</n-button>
</template>
<script setup>
import { NButton } from 'naive-ui'
</script>Install Globally (Not Recommended)
Install All Components
No tree-shaking. Bundle will have redundant codes.
If you want to install globally but don't want all components, please see Import on Demand.
import naive from 'naive-ui'
import { createApp } from 'vue'
const app = createApp(App)
app.use(naive)After the installation, you can use all the components in your SFC like this.
<template>
<n-button>naive-ui</n-button>
</template>Volar support (2.24.2)
If you are using Volar, you can specify global component types by configuring compilerOptions.types in tsconfig.json.
// tsconfig.json
{
"compilerOptions": {
// ...
"types": ["naive-ui/volar"]
}
}