jiaiyan 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
Use appropriate max values: Set reasonable max values for overflow
<n-badge :value="count" :max="99">Use dot for status indicators: When only status matters, not count
<n-badge dot type="success">Show zero when meaningful: Use
show-zerowhen zero is a valid state<n-badge :value="0" show-zero>Use processing for loading states: Show processing animation during async operations
<n-badge :value="pending" processing>Consistent positioning: Use offset sparingly and consistently across the app
Accessibility: Ensure badge purpose is clear from context