n-icon

Icon component for displaying SVG icons with customizable size, color, and depth. Invoke when user needs to implement icons, icon wrappers, or integrate icon libraries in Naive UI.

SKILL.md

GitHub

Naive UI Icon Component

Icon component for displaying SVG icons with customizable size, color, and depth. Recommended to use with xicons.

When to Use

Use this component when:

  • UI icons: Display action icons, status indicators, or navigation icons
  • Button icons: Add icons to buttons for better visual communication
  • List icons: Add icons to list items or menu items
  • Status indicators: Show success, warning, or error states
  • Icon buttons: Create icon-only buttons or controls

When to Invoke

Invoke this skill when:

  • User needs to implement icons in the UI
  • User wants to customize icon size or color
  • User needs icons with different depth levels
  • User wants to use icon wrappers for background
  • User asks about integrating icon libraries like xicons
  • User needs custom SVG icons

Features

  • Size Control: Number or string for icon size
  • Color Customization: Custom icon color
  • Depth Levels: 1-5 depth levels for matching text colors
  • Component Prop: Pass icon component directly
  • Icon Wrapper: Background wrapper for icons
  • Custom SVG Support: Use custom SVG elements
  • Icon Library Integration: Works with xicons and other icon libraries

API Reference

Icon Props

Name Type Default Description
color string undefined Icon color.
depth 1 | 2 | 3 | 4 | 5 undefined Icon depth.
size number | string undefined Icon size (when the unit is not specified the default unit is px).
component Component undefined Icon component to display.

IconWrapper Props

Name Type Default Description
border-radius number 6 Border radius.
color string undefined Color.
icon-color string undefined Icon color.
size number 24 Size.

Icon Slots

Name Parameters Description
default () The content of the icon.

Basic Usage

Basic Icons

<template>
  <n-space>
    <n-icon size="40">
      <GameControllerOutline />
    </n-icon>
    <n-icon size="40" color="#0e7a0d">
      <GameController />
    </n-icon>
    <n-icon size="40" :component="GameController" />
  </n-space>
</template>

Icon Sizes

<template>
  <n-space align="center">
    <n-icon size="16">
      <CashOutline />
    </n-icon>
    <n-icon size="24">
      <CashOutline />
    </n-icon>
    <n-icon size="32">
      <CashOutline />
    </n-icon>
    <n-icon size="48">
      <CashOutline />
    </n-icon>
  </n-space>
</template>

Icon Colors

<template>
  <n-space>
    <n-icon size="24" color="#18a058">
      <CheckmarkCircle />
    </n-icon>
    <n-icon size="24" color="#2080f0">
      <InformationCircle />
    </n-icon>
    <n-icon size="24" color="#f0a020">
      <Warning />
    </n-icon>
    <n-icon size="24" color="#d03050">
      <CloseCircle />
    </n-icon>
  </n-space>
</template>

Icon Depth

<template>
  <n-space>
    <n-icon :component="CashOutline" size="40" :depth="1" />
    <n-icon :component="CashOutline" size="40" :depth="2" />
    <n-icon :component="CashOutline" size="40" :depth="3" />
    <n-icon :component="CashOutline" size="40" :depth="4" />
    <n-icon :component="CashOutline" size="40" :depth="5" />
  </n-space>
</template>

Custom SVG Icon

<template>
  <n-icon size="40">
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
      <path
        d="M368.5 240H272v-96.5c0-8.8-7.2-16-16-16s-16 7.2-16 16V240h-96.5c-8.8 0-16 7.2-16 16 0 4.4 1.8 8.4 4.7 11.3 2.9 2.9 6.9 4.7 11.3 4.7H240v96.5c0 4.4 1.8 8.4 4.7 11.3 2.9 2.9 6.9 4.7 11.3 4.7 8.8 0 16-7.2 16-16V272h96.5c8.8 0 16-7.2 16-16s-7.2-16-16-16z"
      />
    </svg>
  </n-icon>
</template>

Icon with Background

<template>
  <n-icon-wrapper :size="24" :border-radius="10">
    <n-icon :size="18" :component="Checkmark16Filled" />
  </n-icon-wrapper>
</template>

Common Patterns

Icon in Button

<template>
  <n-space>
    <n-button>
      <template #icon>
        <n-icon><AddIcon /></n-icon>
      </template>
      Add Item
    </n-button>
    <n-button circle>
      <template #icon>
        <n-icon><SettingsIcon /></n-icon>
      </template>
    </n-button>
  </n-space>
</template>

Status Icons

<template>
  <n-space>
    <n-tag type="success">
      <template #icon>
        <n-icon :component="CheckmarkCircle" />
      </template>
      Success
    </n-tag>
    <n-tag type="warning">
      <template #icon>
        <n-icon :component="Warning" />
      </template>
      Warning
    </n-tag>
    <n-tag type="error">
      <template #icon>
        <n-icon :component="CloseCircle" />
      </template>
      Error
    </n-tag>
  </n-space>
</template>

Icon with Avatar

<template>
  <n-avatar>
    <n-icon>
      <PersonOutline />
    </n-icon>
  </n-avatar>
</template>

Icon List

<template>
  <n-list>
    <n-list-item v-for="item in menuItems" :key="item.id">
      <template #prefix>
        <n-icon :component="item.icon" />
      </template>
      {{ item.label }}
    </n-list-item>
  </n-list>
</template>

<script setup>
import { ref } from 'vue'
import { HomeOutline, SettingsOutline, PersonOutline } from '@vicons/ionicons5'

const menuItems = ref([
  { id: 1, label: 'Home', icon: HomeOutline },
  { id: 2, label: 'Settings', icon: SettingsOutline },
  { id: 3, label: 'Profile', icon: PersonOutline },
])
</script>

Icon with Tooltip

<template>
  <n-tooltip>
    <template #trigger>
      <n-icon size="20" style="cursor: pointer">
        <InformationCircle />
      </n-icon>
    </template>
    This is a helpful tooltip
  </n-tooltip>
</template>

Icon Wrapper Variants

<template>
  <n-space>
    <n-icon-wrapper :size="32" color="#18a058" icon-color="#fff">
      <n-icon :size="20" :component="CheckmarkCircle" />
    </n-icon-wrapper>
    <n-icon-wrapper :size="32" color="#2080f0" icon-color="#fff">
      <n-icon :size="20" :component="InformationCircle" />
    </n-icon-wrapper>
    <n-icon-wrapper :size="32" color="#d03050" icon-color="#fff">
      <n-icon :size="20" :component="CloseCircle" />
    </n-icon-wrapper>
  </n-space>
</template>

Using Component Prop

<template>
  <n-space>
    <n-icon :component="HomeOutline" size="24" />
    <n-icon :component="SettingsOutline" size="24" />
    <n-icon :component="PersonOutline" size="24" />
  </n-space>
</template>

<script setup>
import { HomeOutline, SettingsOutline, PersonOutline } from '@vicons/ionicons5'
</script>

Best Practices

  1. Use recommended icon libraries: Use xicons for consistent icon sets

    <script setup>
    import { HomeOutline } from '@vicons/ionicons5'
    </script>
    
  2. Match icon size with text: Use appropriate sizes for different contexts

    • 16px for inline with small text
    • 20px for inline with regular text
    • 24px for standard icons
    • 32px+ for feature icons
  3. Use depth for hierarchy: Match icon depth with surrounding text

    <n-text depth="3">
      <n-icon :depth="3"><InfoIcon /></n-icon>
      Secondary information
    </n-text>
    
  4. Ensure SVG viewBox is set: Custom SVG icons must have viewBox attribute

    <n-icon>
      <svg viewBox="0 0 24 24">
        <!-- SVG content -->
      </svg>
    </n-icon>
    
  5. Use icon-wrapper for emphasis: Add background for important icons

    <n-icon-wrapper color="#18a058">
      <n-icon :component="CheckIcon" />
    </n-icon-wrapper>
    
  6. Consistent icon style: Use the same icon family throughout the application

    • Use outline icons for UI elements
    • Use filled icons for emphasis or active states
  7. Accessibility: Add aria-label for standalone icons

    <n-icon size="20" aria-label="Settings">
      <SettingsOutline />
    </n-icon>