## File: README.md

<h1 align="center">Naive UI</h1>








## Documentation

[www.naiveui.com](http://www.naiveui.com)

## Community

- [Discord](https://discord.gg/Pqv7Mev5Dd)
- 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

- [Awesome Naive UI](https://github.com/naive-ui/awesome-naive)

## 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.

```bash
npm i naive-ui
```

### Fonts

```bash
npm i vfonts
```

### Icons

Naive UI recommends using [xicons](https://www.xicons.org) as icon library.

### Design Resources

[Naive UI (Sketch)](https://naive-ui.oss-accelerate.aliyuncs.com/NaiveUI-Design-Library-en-US.sketch).

## Contributing

Please see [CONTRIBUTING.md](https://github.com/tusen-ai/naive-ui/blob/main/CONTRIBUTING.md).

## License

Naive UI is licensed under the [MIT license](https://opensource.org/licenses/MIT).

Graphics resources of `result` component is licensed under the [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/). The graphics resources come from [Twemoji](https://github.com/twitter/twemoji).

---

## File: demo/pages/docs/vitepress/zhCN/index.md

# Vitepress

## 注意

本文档涉及到 SSR，请先了解[SSR 的注意事项](ssr#注意)。

## 例子

这是一个使用 `naive-ui`、`vitepress` 的[样例](https://github.com/07akioni/naive-ui-vitepress-demo)，支持 SSR。

你可以直接使用这个样例。

## 从零开始的关键步骤

如果你希望从头开始改造一个 vitepress 项目，遵循下列步骤

### 0. 安装 `@css-render/vue3-ssr`

确保其版本 `>=0.15.14`。

```bash
# npm
npm install --save-dev @css-render/vue3-ssr

# pnpm
pnpm install --save-dev @css-render/vue3-ssr
```

### 1. 把下面的内容增加到 `.vitepress/theme/index.js`

```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`

```ts
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

```md
...

<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](ssr#Caveat) before proceeding.

## Example

This is a [demo](https://github.com/07akioni/naive-ui-vitepress-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`.

```bash
# npm
npm install --save-dev @css-render/vue3-ssr

# pnpm
pnpm install --save-dev @css-render/vue3-ssr
```

### 1. Add this content to `.vitepress/theme/index.js`

```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`

```ts
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

```md
...

<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 的注意事项](ssr#注意)。

## 配置指南

如果你正在使用 `vite-sse` 或者 `vite-ssg`，通过下面的步骤设定 `naive-ui`。

### 1. 安装 `naive-ui`、`@css-render/vue3-ssr`

```bash
# pnpm
pnpm i naive-ui @css-render/vue3-ssr

# npm
npm i naive-ui @css-render/vue3-ssr
```

### 2. 修改 `vite.config.ts`

增加下列内容，如果已经存在一些内容，则合并他们。

```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](ssr#Caveat) 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`

```bash
# pnpm
pnpm i naive-ui @css-render/vue3-ssr

# npm
npm i naive-ui @css-render/vue3-ssr
```

### 2. Modify `vite.config.ts`

Add following content. If there exists content already, merge them.

```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>`
      )
    }
  }
})
```

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 中。

## 直接引入（推荐）

你可以直接导入组件并使用它。这种情况下，只有导入的组件才会被打包。

如果你想知道如何按需引入主题和语言包，请参考[按需引入](import-on-demand)。

```html
<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，你可以用下面的方式使用组件。

```html
<template>
  <n-button>naive-ui</n-button>
</template>

<script setup>
  import { NButton } from 'naive-ui'
</script>
```

## 全局安装（不推荐）

### 安装全部组件

失去 tree-shaking 的能力，打包有冗余代码。

如果你想全局安装但是不想安装全部组件，请参考[按需引入](import-on-demand)。

```js
import naive from 'naive-ui'
import { createApp } from 'vue'

const app = createApp(App)
app.use(naive)
```

安装后，你可以这样在 SFC 中使用全部组件。

```html
<template>
  <n-button>naive-ui</n-button>
</template>
```

### Volar 支持（2.24.2）

如果你在使用 Volar，那么可以在 `tsconfig.json` 中配置 `compilerOptions.types` 来指定全局组件类型。

```json
// 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](import-on-demand).

```html
<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.

```html
<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-on-demand).

```js
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.

```html
<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`.

```json
// tsconfig.json
{
  "compilerOptions": {
    // ...
    "types": ["naive-ui/volar"]
  }
}
```