Skip to content
Get packs

Guide · Open source

How to use Naive UI: install and build Vue 3 components

Updated · written with AI from the project's own documentation and checked against our catalogue data

Naive UI is a component library for Vue 3, a set of ready-made interface pieces such as buttons, forms and tables. It is written in TypeScript and is aimed at developers who want to build admin panels and internal tools without writing every component from scratch. After this guide you will know how to install Naive UI with npm, add the optional fonts package, and understand how theming works.

Naive UItusen-ai/naive-ui · ★ 18.6k · MIT

Quick start

  1. 1Check prerequisites. Confirm that Node.js and npm are installed and that your project uses Vue 3.
  2. 2Install the package. Run npm i naive-ui in your project folder.
  3. 3Install fonts if wanted. Optionally run npm i vfonts to add the fonts package.
  4. 4Read the docs. Open www.naiveui.com to see component APIs and usage examples.
  5. 5Add a theme overrides object. Write your theme overrides in JavaScript to restyle components instead of editing CSS.

What you need before you install Naive UI

Naive UI is a Vue 3 library installed through a package manager. The project's README lists Node.js and npm as the prerequisites, so make sure both are available in your environment before you start.

The README describes Naive UI as a Vue 3 library. If your project does not use Vue 3, this library is not the intended fit.

  • Node.js and npm installed
  • An existing Vue 3 project

Install Naive UI from npm

Run the install command from the root of your Vue project. The README gives this command for installing the package from npm.

npm i naive-ui

Install the optional fonts package

The README lists a separate fonts package called vfonts. Installing it is optional; run this command only if you want to use the fonts it provides.

npm i vfonts

Customize the theme with an overrides object

Naive UI's theme system is type safe and built with TypeScript. According to the README, you provide a theme overrides object in JavaScript and the library handles the rest. The README also says no Less, Sass or CSS variables and no webpack loaders are required for this.

The README also says you do not need to import any CSS to use the components.

  • Write a theme overrides object in JavaScript
  • Pass it to the components rather than editing CSS files
  • No Less, Sass, CSS variables or webpack loaders are needed according to the README

Choose components and icons

Naive UI has more than 90 components, and the README says they are all treeshakable, so only the parts you import are meant to be bundled. For icons, the README recommends xicons at xicons.org.

Data components support virtual lists by default, which the README presents as part of its speed claims. This matters most when you show long lists of data.

  • More than 90 components, all treeshakable
  • Icon library recommended by the README: xicons
  • Data components use virtual lists by default

Find documentation and design resources

The official documentation is at www.naiveui.com. The README also links a Sketch design library for designers who work in that tool, and a community Discord and an Awesome Naive UI list on GitHub.

Naive UI is licensed under the MIT license.

  • Documentation: www.naiveui.com
  • Community: Discord and DingTalk groups listed in the README
  • Sketch design library linked in the README

What people use it for

  • Admin panels and back-office dashboards built with Vue 3
  • Internal tools where teams want typed components in a TypeScript project
  • Apps that display large data lists, using the default virtual list support in data components
  • Projects that want a consistent look controlled by one theme object

Frequently asked questions

Is Naive UI free to use?

Yes. The README says Naive UI is licensed under the MIT license. The README's graphics note also says the result component's graphics are under CC-BY 4.0, and they come from Twemoji.

How do I install Naive UI?

Run npm i naive-ui in your project. The README lists Node.js and npm as prerequisites. Installing the vfonts package with npm i vfonts is optional.

Does Naive UI work with TypeScript?

The README says all of Naive UI is written in TypeScript and can work seamlessly with TypeScript projects. Its theme system is also described as type safe.

Do I need to import CSS to use Naive UI?

According to the README, no. You do not need to import any CSS to use the components, and no Less, Sass or CSS variables are required for theming.

Can Naive UI be used with Vue 2?

The README describes Naive UI as a Vue 3 component library, so it is written for Vue 3 projects. Check the documentation at www.naiveui.com before using it in another setup.

How does Naive UI compare to Element Plus or Vuetify?

The source mentions Element Plus, Vuetify, Quasar and Ant Design Vue as comparable projects but does not compare them in detail. Choose based on your design needs, theme approach and team familiarity.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Naive UI suits Vue 3 developers building admin panels, internal tools or TypeScript projects that want typed components and theming through a JavaScript object. It is a poor fit if your project does not use Vue 3, if you already use another UI library's design system, or if you need a non-developer to make design changes directly.

Install options & downloads