n-badge

Badge component for displaying status indicators and notification counts. Invoke when user needs to show numerical badges, status dots, or custom badge content in Naive UI.

SKILL.md

GitHub

Naive UI Badge Component

Badge component for displaying notification counts, status indicators, and labels on elements.

When to Use

Use this component when:

  • Notification counts: Display unread message counts
  • Status indicators: Show online/offline or processing status
  • Labels: Add labels or tags to elements
  • Visual markers: Highlight elements with dots or numbers

When to Invoke

Invoke this skill when:

  • User needs to display notification counts on avatars or icons
  • User wants to create status dot indicators
  • User needs to show overflow numbers (e.g., 99+)
  • User wants to customize badge colors or content
  • User asks about badge positioning or visibility control

Features

  • Multiple Types: default, info, success, warning, error
  • Dot Mode: Display as a small dot indicator
  • Overflow Handling: Max value support for large numbers
  • Processing Animation: Animated processing indicator
  • Custom Content: Support for text or custom content
  • Custom Colors: Customizable badge colors
  • Position Offset: Adjustable badge position
  • Visibility Control: Show/hide badges conditionally

API Reference

Badge Props

Name Type Default Description
color string undefined Badge color.
dot boolean false Show badge as dot.
max number undefined The maximum number of the badge when its value overflows.
offset [string | number, string | number] undefined Offset of the badge from the left and top of the default position.
processing boolean false Show processing status.
show-zero boolean false Whether to display the badge, even if provided value equals 0.
show boolean true Whether the badge should be shown altogether.
type 'default' | 'success' | 'error' | 'warning' | 'info' 'default' Type of the badge.
value string | number undefined Badge's value.

Badge Slots

Name Parameters Description
default () Badge's content.
value () Custom badge value content.

Basic Usage

Basic Badge

<template>
  <n-space :size="24" align="center">
    <n-badge :value="5">
      <n-avatar />
    </n-badge>
    <n-badge :value="20">
      <n-avatar />
    </n-badge>
  </n-space>
</template>

Dot Badge

<template>
  <n-space :size="24" align="center">
    <n-badge dot>
      <n-avatar />
    </n-badge>
    <n-badge dot type="error">
      <n-avatar />
    </n-badge>
    <n-badge dot type="info">
      <n-avatar />
    </n-badge>
    <n-badge dot type="success">
      <n-avatar />
    </n-badge>
    <n-badge dot type="warning">
      <n-avatar />
    </n-badge>
  </n-space>
</template>

Badge Types

<template>
  <n-space :size="24" align="center">
    <n-badge :value="10" type="default">
      <n-avatar />
    </n-badge>
    <n-badge :value="10" type="error">
      <n-avatar />
    </n-badge>
    <n-badge :value="10" type="info">
      <n-avatar />
    </n-badge>
    <n-badge :value="10" type="success">
      <n-avatar />
    </n-badge>
    <n-badge :value="10" type="warning">
      <n-avatar />
    </n-badge>
  </n-space>
</template>

Processing Animation

<template>
  <n-space :size="24" align="center">
    <n-badge dot processing>
      <n-avatar />
    </n-badge>
    <n-badge :value="20" processing>
      <n-avatar />
    </n-badge>
    <n-badge dot type="info" processing>
      <n-avatar />
    </n-badge>
  </n-space>
</template>

Overflow Handling

<template>
  <n-space :size="24" align="center">
    <n-badge :value="99" :max="99">
      <n-avatar />
    </n-badge>
    <n-badge :value="100" :max="99">
      <n-avatar />
    </n-badge>
    <n-badge :value="1000" :max="999">
      <n-avatar />
    </n-badge>
  </n-space>
</template>

Show Zero

<template>
  <n-space :size="24" align="center">
    <n-badge :value="0">
      <n-avatar />
    </n-badge>
    <n-badge :value="0" show-zero>
      <n-avatar />
    </n-badge>
  </n-space>
</template>

Custom Content

<template>
  <n-space :size="24" align="center">
    <n-badge value="new">
      <n-avatar />
    </n-badge>
    <n-badge value="hot">
      <n-avatar />
    </n-badge>
    <n-badge processing>
      <n-avatar />
      <template #value>
        <n-icon :component="LockClosedOutline" />
      </template>
    </n-badge>
  </n-space>
</template>

Custom Color

<template>
  <n-badge value="15" color="grey">
    <n-avatar />
  </n-badge>
</template>

Position Offset

<template>
  <n-badge :value="5" :offset="[10, 10]">
    <n-avatar />
  </n-badge>
</template>

Controlled Visibility

<template>
  <n-space :size="24" align="center">
    <n-badge :value="5" :show="show">
      <n-avatar />
    </n-badge>
    <n-button @click="show = !show">
      Toggle Badge
    </n-button>
  </n-space>
</template>

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

const show = ref(true)
</script>

Standalone Badge (No Wrapper)

<template>
  <n-space :size="24" align="center">
    <n-badge :value="5" :max="15" />
    <n-badge :value="10" dot />
  </n-space>
</template>

Common Patterns

Notification Icon with Count

<template>
  <n-badge :value="unreadCount" :max="99">
    <n-button circle quaternary>
      <template #icon>
        <n-icon><BellIcon /></n-icon>
      </template>
    </n-button>
  </n-badge>
</template>

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

const unreadCount = ref(25)
</script>

Status Indicator

<template>
  <n-space align="center">
    <n-badge dot :type="isOnline ? 'success' : 'default'" />
    <span>{{ isOnline ? 'Online' : 'Offline' }}</span>
  </n-space>
</template>

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

const isOnline = ref(true)
</script>

Dynamic Badge Value

<template>
  <n-space align="center">
    <n-badge :value="count" :max="99">
      <n-avatar />
    </n-badge>
    <n-button-group>
      <n-button @click="count = Math.max(0, count - 1)">-</n-button>
      <n-button @click="count = Math.min(999, count + 1)">+</n-button>
    </n-button-group>
  </n-space>
</template>

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

const count = ref(5)
</script>

Best Practices

  1. Use appropriate max values: Set reasonable max values for overflow

    <n-badge :value="count" :max="99">
    
  2. Use dot for status indicators: When only status matters, not count

    <n-badge dot type="success">
    
  3. Show zero when meaningful: Use show-zero when zero is a valid state

    <n-badge :value="0" show-zero>
    
  4. Use processing for loading states: Show processing animation during async operations

    <n-badge :value="pending" processing>
    
  5. Consistent positioning: Use offset sparingly and consistently across the app

  6. Accessibility: Ensure badge purpose is clear from context