n-badge

name	n-badge
description	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.
metadata	{"author":"jiaiyan","version":"1.0.0"}

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