opencloud/.agents/skills/naive-ui-components/SKILL.md

name, description, metadata

name	description	metadata
naive-ui-components	Comprehensive overview of all Naive UI components organized by category. Invoke when user needs to discover available components, understand component categories, or find the right component for their use case.	author version jiaiyan 1.0.0

Naive UI Components Overview

Naive UI is a Vue 3 component library with over 90 components. All components are tree-shakable, written in TypeScript, and fully themeable. This skill provides a comprehensive index of all available components organized by category.

When to Use

Use this skill when:

• Component discovery: Finding the right component for a specific use case
• Project planning: Understanding available UI building blocks
• Component selection: Choosing between similar components
• Learning Naive UI: Getting an overview of the component library
• Migration planning: Understanding component equivalents from other libraries

When to Invoke

Invoke this skill when:

• User asks what components are available in Naive UI
• User needs to find a component for a specific UI pattern
• User wants to understand component categories
• User is new to Naive UI and needs an overview
• User asks about component count or coverage

Prerequisites

• Naive UI installed (npm install naive-ui)
• Vue 3 application setup
• Basic understanding of Vue 3 composition API

Component Library Overview

Metric	Value
Total Components	90+
Tree-shakable	Yes
TypeScript	Full support
Theme System	Built-in CSS-in-JS
SSR Support	Yes

Component Categories

1. Common Components (18)

Basic UI elements used throughout applications.

Component	Tag	Description	Skill Path
Button	n-button	Buttons with various types and states	n-button
Button Group	n-button-group	Button group container	n-button-group
Icon	n-icon	Icon wrapper component	n-icon
Icon Wrapper	n-icon-wrapper	Icon with background	n-icon-wrapper
Tag	n-tag	Tags and labels	n-tag
Badge	n-badge	Badges and marks	n-badge
Avatar	n-avatar	User avatars	n-avatar
Avatar Group	n-avatar-group	Avatar group display	n-avatar-group
Card	n-card	Card containers	n-card
Divider	n-divider	Dividing lines	n-divider
Collapse	n-collapse	Collapsible panels	n-collapse
Collapse Transition	n-collapse-transition	Collapse animation	n-collapse-transition
Ellipsis	n-ellipsis	Text ellipsis	n-ellipsis
Typography	n-typography	Typography components	n-typography
Gradient Text	n-gradient-text	Gradient text effect	n-gradient-text
Thing	n-thing	Thing container	n-thing
Element	n-element	Element wrapper	n-element
Code	n-code	Code display	n-code

2. Data Input Components (26)

Form controls and input components.

Component	Tag	Description	Skill Path
Input	n-input	Text input	n-input
Input Number	n-input-number	Number input	n-input-number
Input OTP	n-input-otp	OTP input	n-input-otp
Auto Complete	n-auto-complete	Input with suggestions	n-auto-complete
Select	n-select	Dropdown select	n-select
Tree Select	n-tree-select	Tree select	n-tree-select
Cascader	n-cascader	Cascading selection	n-cascader
Checkbox	n-checkbox	Checkboxes	n-checkbox
Radio	n-radio	Radio buttons	n-radio
Switch	n-switch	Toggle switch	n-switch
Slider	n-slider	Slider input	n-slider
Rate	n-rate	Star rating	n-rate
Color Picker	n-color-picker	Color picker	n-color-picker
Date Picker	n-date-picker	Date picker	n-date-picker
Time Picker	n-time-picker	Time picker	n-time-picker
Form	n-form	Form management	n-form
Dynamic Input	n-dynamic-input	Dynamic input fields	n-dynamic-input
Dynamic Tags	n-dynamic-tags	Dynamic tags input	n-dynamic-tags
Mention	n-mention	Mention input	n-mention
Transfer	n-transfer	Transfer panels	n-transfer
Upload	n-upload	File upload	n-upload
QR Code	n-qr-code	QR code generator	n-qr-code
Float Button	n-float-button	Floating button	n-float-button
Float Button Group	n-float-button-group	Floating button group	n-float-button-group

3. Data Display Components (20)

Components for presenting data.

Component	Tag	Description	Skill Path
DataTable	n-data-table	Advanced data table	n-data-table
Table	n-table	Basic table	n-table
Tree	n-tree	Tree view	n-tree
List	n-list	List container	n-list
Descriptions	n-descriptions	Description list	n-descriptions
Statistic	n-statistic	Statistics display	n-statistic
Number Animation	n-number-animation	Animated numbers	n-number-animation
Countdown	n-countdown	Countdown timer	n-countdown
Time	n-time	Time display	n-time
Timeline	n-timeline	Timeline display	n-timeline
Calendar	n-calendar	Calendar view	n-calendar
Image	n-image	Image with preview	n-image
Empty	n-empty	Empty state	n-empty
Result	n-result	Result page	n-result
Skeleton	n-skeleton	Loading skeleton	n-skeleton
Progress	n-progress	Progress bar	n-progress
Spin	n-spin	Loading spinner	n-spin
Log	n-log	Log display	n-log
Heatmap	n-heatmap	Heatmap visualization	n-heatmap
Equation	n-equation	Math equation	n-equation

4. Navigation Components (12)

Navigation and wayfinding components.

Component	Tag	Description	Skill Path
Menu	n-menu	Navigation menu	n-menu
Tabs	n-tabs	Tabs	n-tabs
Breadcrumb	n-breadcrumb	Breadcrumb navigation	n-breadcrumb
Anchor	n-anchor	Anchor navigation	n-anchor
Dropdown	n-dropdown	Dropdown menu	n-dropdown
Popselect	n-popselect	Popover select	n-popselect
Steps	n-steps	Steps guide	n-steps
Pagination	n-pagination	Pagination	n-pagination
Affix	n-affix	Sticky positioning	n-affix
Back Top	n-back-top	Back to top button	n-back-top
Page Header	n-page-header	Page header	n-page-header

5. Feedback Components (11)

User feedback and notification components.

Component	Tag	Description	Skill Path
Dialog	n-dialog	Modal dialog	n-dialog
Modal	n-modal	Modal container	n-modal
Drawer	n-drawer	Drawer panel	n-drawer
Message	n-message	Toast message	n-message
Notification	n-notification	Notification	n-notification
Popconfirm	n-popconfirm	Popconfirm	n-popconfirm
Popover	n-popover	Popover	n-popover
Tooltip	n-tooltip	Tooltip	n-tooltip
Alert	n-alert	Alert messages	n-alert
Loading Bar	n-loading-bar	Loading bar	n-loading-bar
Discrete	n-discrete	Discrete API	n-discrete

6. Layout Components (9)

Page structure and layout components.

Component	Tag	Description	Skill Path
Layout	n-layout	Layout container	n-layout
Grid	n-grid	Grid system	n-grid
Legacy Grid	n-legacy-grid	Legacy grid	n-legacy-grid
Flex	n-flex	Flex container	n-flex
Space	n-space	Spacing	n-space
Split	n-split	Split panels	n-split
Carousel	n-carousel	Image carousel	n-carousel
Marquee	n-marquee	Marquee animation	n-marquee

7. Utility Components (8)

Helper and configuration components.

Component	Tag	Description	Skill Path
Config Provider	n-config-provider	Global config	n-config-provider
Scrollbar	n-scrollbar	Custom scrollbar	n-scrollbar
Virtual List	n-virtual-list	Virtual scroll list	n-virtual-list
Infinite Scroll	n-infinite-scroll	Infinite scroll	n-infinite-scroll
Watermark	n-watermark	Watermark	n-watermark
Global Style	n-global-style	Global styles	n-global-style
Highlight	n-highlight	Code highlight	n-highlight

Basic Usage

Importing Components

Naive UI supports both global and on-demand imports:

// Global import
import naive from 'naive-ui'
app.use(naive)

// On-demand import (tree-shakable)
import { NButton, NInput, NCard } from 'naive-ui'

app.component('NButton', NButton)
app.component('NInput', NInput)
app.component('NCard', NCard)

Using Components in Templates

<template>
  <n-space vertical>
    <n-card title="Welcome">
      <n-input v-model:value="text" placeholder="Type something" />
      <n-button type="primary" @click="handleClick">
        Submit
      </n-button>
    </n-card>
  </n-space>
</template>

<script setup>
import { ref } from 'vue'

const text = ref('')

const handleClick = () => {
  console.log(text.value)
}
</script>

Common Patterns

Form with Validation

<template>
  <n-form ref="formRef" :model="model" :rules="rules">
    <n-form-item label="Name" path="name">
      <n-input v-model:value="model.name" />
    </n-form-item>
    <n-form-item label="Email" path="email">
      <n-input v-model:value="model.email" />
    </n-form-item>
    <n-form-item>
      <n-button type="primary" @click="submit">Submit</n-button>
    </n-form-item>
  </n-form>
</template>

<script setup>
import { ref, reactive } from 'vue'

const formRef = ref()
const model = reactive({ name: '', email: '' })
const rules = {
  name: [{ required: true, message: 'Name required' }],
  email: [{ required: true, type: 'email', message: 'Valid email required' }]
}

const submit = async () => {
  await formRef.value?.validate()
}
</script>

Data Table with Actions

<template>
  <n-data-table
    :columns="columns"
    :data="data"
    :pagination="pagination"
  />
</template>

<script setup>
import { h } from 'vue'
import { NButton, useMessage } from 'naive-ui'

const message = useMessage()

const columns = [
  { title: 'Name', key: 'name' },
  { title: 'Age', key: 'age' },
  {
    title: 'Actions',
    key: 'actions',
    render(row) {
      return h(NButton, {
        size: 'small',
        onClick: () => message.info(`Edit ${row.name}`)
      }, { default: () => 'Edit' })
    }
  }
]

const data = [
  { name: 'John', age: 30 },
  { name: 'Jane', age: 25 }
]

const pagination = { pageSize: 10 }
</script>

Modal Dialog

<template>
  <n-button @click="showModal = true">Open Modal</n-button>
  
  <n-modal v-model:show="showModal" preset="dialog" title="Confirm">
    <p>Are you sure you want to proceed?</p>
    <template #action>
      <n-button @click="showModal = false">Cancel</n-button>
      <n-button type="primary" @click="confirm">Confirm</n-button>
    </template>
  </n-modal>
</template>

<script setup>
import { ref } from 'vue'

const showModal = ref(false)

const confirm = () => {
  showModal.value = false
}
</script>

Component Selection Guide

When to Use Which Component

Use Case	Recommended Component
Primary action	n-button with type="primary"
Text input	n-input
Selection from list	n-select
Boolean toggle	n-switch or n-checkbox
Date selection	n-date-picker
Form layout	n-form with n-form-item
Data grid	n-data-table
Navigation	n-menu or n-tabs
Modal content	n-modal or n-dialog
User feedback	n-message or n-notification
Page layout	n-layout with n-layout-header, n-layout-content
Card container	n-card
Loading state	n-spin or n-skeleton

Best Practices

1. Use on-demand imports: Import only needed components for smaller bundles

   import { NButton, NInput } from 'naive-ui'
   

2. Wrap app with n-config-provider: Configure theme, locale, and defaults globally

   <n-config-provider :theme="theme">
     <App />
   </n-config-provider>
   

3. Use n-global-style with themes: Sync global styles when using dark mode

   <n-config-provider :theme="theme">
     <n-global-style />
     <App />
   </n-config-provider>
   

4. Leverage provider components: Use message, dialog, notification providers

   <n-message-provider>
     <n-dialog-provider>
       <n-notification-provider>
         <App />
       </n-notification-provider>
     </n-dialog-provider>
   </n-message-provider>
   

5. Use TypeScript: Take advantage of full type definitions

   import type { DataTableColumns, FormRules } from 'naive-ui'
   

6. Follow naming conventions: Use n- prefix in templates

   <n-button>Click</n-button>
   

7. Use composition API: Components work best with Vue 3 composition API

   <script setup>
   import { ref } from 'vue'
   const value = ref('')
   </script>
   

Related Skills

• naive-ui-quickstart: Installation and setup
• naive-ui-theming: Theme customization
• naive-ui-dark-mode: Dark mode implementation
• naive-ui-ssr: Server-side rendering
• n-config-provider: Global configuration