Quick Start
NsUI is a Vue 3 component library made up of 4 packages:
| Package | Contents |
|---|---|
@ns/ui | All components (86), the v-loading directive, and functional APIs like Message |
@ns/theme | Theme: CSS variables, dark theme, 6 color palettes, reset styles, utility classes |
@ns/icons | SVG icons |
@ns/utils | Utilities (type checks, debounce and throttle, DOM helpers) |
Most projects only need to install @ns/ui. The other three packages are its dependencies and are installed along with it.
Requirements
- Vue 3.5 or later (Modal, Drawer and Popover use
useId, added in Vue 3.5) - Node.js 18 or later
- Browsers: Chrome / Edge 111, Firefox 113, Safari 16.2 or later (the theme's light color scale uses CSS
color-mix; older browsers fall back to fixed colors)
Installation
The packages are currently published to the company's Nexus registry. First add a line to the .npmrc at your project root so that packages starting with @ns are installed from Nexus:
@ns:registry=https://nexus.nscode.cn/repository/npm-group/
Then install:
pnpm add @ns/ui
# or
npm install @ns/ui
Full Import
Register the library once in your entry file. After that every component can be used in templates directly, without importing them one by one.
// main.ts
import { createApp } from 'vue'
import NsUI from '@ns/ui'
import '@ns/ui/style.css'
import App from './App.vue'
const app = createApp(App)
app.use(NsUI)
app.mount('#app')
app.use(NsUI) does two things:
- Registers every component. Tag names are PascalCase with an
Nsprefix, such as<NsButton>,<NsDatePicker>and<NsFormItem>; - Registers the
v-loadingdirective.
<template>
<NsButton type="primary" @click="count++">Clicked {{ count }} times</NsButton>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const count = ref(0)
</script>
On-demand Import
If you only use a few components, skip app.use(NsUI) and import them where they are used. The style file still needs to be imported once in the entry file.
// main.ts
import '@ns/ui/style.css'
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsInput } from '@ns/ui'
const keyword = ref('')
</script>
<template>
<NsInput v-model="keyword" placeholder="Enter a keyword" />
<NsButton type="primary">Search</NsButton>
</template>
With on-demand import, register the v-loading directive yourself:
import { vLoading } from '@ns/ui'
app.directive('loading', vLoading)
Inside <script setup> you can also import { vLoading } from '@ns/ui' directly. Because the variable is named vLoading, v-loading works in the template.
Functional APIs
Message, MessageBox, Notification and full-screen Loading are not written in templates. Call them as functions:
import { NsMessage, NsMessageBox, NsNotification, NsLoading } from '@ns/ui'
NsMessage.success('Saved')
NsMessageBox.confirm('Delete this record?', 'Confirm')
.then(() => {
// OK was clicked
})
.catch(() => {
// Cancel or close was clicked
})
NsNotification({ title: 'Notice', message: 'You have a new message' })
const loading = NsLoading.service({ fullscreen: true, text: 'Loading...' })
loading.close()
See each component's page for the full options.
TypeScript
Props, events and option shapes of every component are typed. Import the types from @ns/ui:
import type { ButtonProps, SelectOption, TableColumnConfig, FormRule } from '@ns/ui'
The "Types" section of each component page lists the types it exports.
Global Configuration
To set the default component size, the default button type and the z-index of overlays in one place, wrap your app with NsConfigProvider:
<template>
<NsConfigProvider size="small" :z-index="3000">
<App />
</NsConfigProvider>
</template>
A size written on the component itself wins, and a size on Form, ButtonGroup and similar containers also wins over the global setting. Which components read these settings is listed in the notes of ConfigProvider.
Notes
@ns/ui/style.cssincludes reset styles:marginandpaddingof all elements are zeroed,box-sizingisborder-box, and media elements such asimgandsvgbecome block-level. When adding NsUI to an existing project, check pages that rely on the browser's default spacing.- The text color and background of
bodycome from theme variables (--ns-text-color,--ns-bg-color), so the page background follows when switching to the dark theme. - Overlays such as dialogs, dropdowns and messages are mounted on
body. Don't rely on parent selectors from your page when styling them.