Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Display

Badge

A compact status or category label.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

defaultsecondaryoutlinesuccesswarningdestructive

Install

Run in your project
bunx --bun @getweini/cli@latest add badge

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

New Draft Live PendingBlockedPreview
Vue
<script setup lang="ts">
import Badge from './components/ui/badge/Badge.vue'
</script>

<template>
  <Badge>New</Badge>
  <Badge variant="secondary" aria-label="Draft, 3 items">
    Draft
    <template #suffix><span aria-hidden="true">3</span></template>
  </Badge>
  <Badge variant="success">
    <template #prefix>
      <span aria-hidden="true" class="size-1.5 rounded-full bg-current" />
    </template>
    Live
  </Badge>
  <Badge variant="warning">Pending</Badge>
  <Badge variant="destructive">Blocked</Badge>
  <Badge variant="outline">Preview</Badge>
</template>

Add text or decorative icons with the prefix and suffix slots. Each slot also has a data-slot attribute for custom styling.

When to use it

Workflow state

Show whether a review is pending, approved, or blocked beside its title.

Small count

Pair a category label with a count in a table cell or list row.

More examples

Review status

Use a word as well as color to communicate the state.

Review status
<script setup lang="ts">
import Badge from './components/ui/badge/Badge.vue'
</script>

<template>
  <p>Change request&nbsp;<Badge variant="warning">Awaiting review</Badge></p>
</template>

Count with context

A suffix can hold a decorative count when the accessible name carries the full meaning.

Count with context
<script setup lang="ts">
import Badge from './components/ui/badge/Badge.vue'
</script>

<template>
  <Badge variant="secondary" aria-label="3 unread messages">
    Unread&nbsp;<template #suffix><span aria-hidden="true">3</span></template>
  </Badge>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Badge

Complete API for Badge
NameType or signatureDefaultWhat it does
variantprop"default" | "success" | "warning" | "destructive" | "secondary" | "outline" | undefined"default"Choose the visual treatment for this component.
defaultslot() => unknownRequiredContent shown inside Badge.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.
Public type definitions
Public types
// packages/frameworks/vue/components/badge/types.ts
import type { badgeVariants } from './styles'

// ------- TYPES -------

export interface BadgeProps {
  variant?: keyof typeof badgeVariants
}


// packages/frameworks/vue/components/badge/styles.ts
// Add or change a Badge color here; the public variant type follows these keys.
export const badgeVariants = {
  default: 'border-transparent bg-primary text-primary-foreground',
  secondary: 'border-transparent bg-secondary text-secondary-foreground',
  outline: 'border-border text-foreground',
  success: 'border-transparent bg-success text-success-foreground',
  warning: 'border-transparent bg-warning text-warning-foreground',
  destructive: 'border-transparent bg-destructive text-destructive-foreground',
} as const

Implementation notes

  • Choose variants by meaning consistently across a product, rather than changing a status color from page to page.
  • A badge describes state; use Button or Link when users need to act.

Accessibility and localization

  • Always include status text so meaning survives color changes and forced-colors display.

Source contract and editing guidance