Badge Overview

Badges are small status descriptors for UI elements, used to convey concise information about an item or its status. They provide a visual way to highlight important information, categorize content, or indicate states in your application. The badge component supports various semantic types, sizes, and icon integration for maximum flexibility.

When to Use

✅ Use badges when:

  • Indicating status or state changes (new, updated, approved)
  • Categorizing or labeling content (tags, categories)
  • Showing counts or quantities (notifications, items)
  • Highlighting important information (featured, urgent)
  • Providing visual feedback for user actions

❌ Don't use badges for:

  • Primary navigation elements (use buttons or links)
  • Large amounts of text (use cards or sections)
  • Interactive actions (use buttons)
  • Complex information display (use dedicated components)
Design system docs Examples Default badge 
<dap-ds-badge>Default Badge</dap-ds-badge>
Badge types

Different types of badges for different statuses

<dap-ds-stack direction="row">
<dap-ds-badge type="neutral">
    Neutral Badge
</dap-ds-badge>
<dap-ds-badge type="brand">
    Brand Badge
</dap-ds-badge>
<dap-ds-badge type="info">
    Info Badge
</dap-ds-badge>
<dap-ds-badge type="positive">
    Positive Badge
</dap-ds-badge>
<dap-ds-badge type="warning">
    Warning Badge
</dap-ds-badge>
<dap-ds-badge type="negative">
    Negative Badge
</dap-ds-badge>
</dap-ds-stack>
Badge sizes

Choose badge sizes based on context and visual hierarchy. Small badges work well for compact layouts, while large badges are more prominent:

<dap-ds-stack direction="row" align="center">
<dap-ds-badge size="sm">
    Small Badge
</dap-ds-badge>
<dap-ds-badge size="lg">
    Large Badge
</dap-ds-badge>
</dap-ds-stack>
Badges with icons

Badges can include icons to provide additional visual context:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Built-in icons</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-badge type="positive" icon="check-line">
      Approved
    </dap-ds-badge>
    <dap-ds-badge type="warning" icon="time-line">
      Pending
    </dap-ds-badge>
    <dap-ds-badge type="negative" icon="close-line">
      Rejected
    </dap-ds-badge>
    <dap-ds-badge type="info" icon="information-line">
      Info
    </dap-ds-badge>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Custom slotted icons</dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-badge type="brand">
      <dap-ds-icon slot="icon" name="star-fill"></dap-ds-icon>
      Featured
    </dap-ds-badge>
    <dap-ds-badge type="neutral">
      <dap-ds-icon slot="icon" name="shield-check-line"></dap-ds-icon>
      Verified
    </dap-ds-badge>
    <dap-ds-badge type="positive">
      <dap-ds-icon slot="icon" name="medal-line"></dap-ds-icon>
      Premium
    </dap-ds-badge>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Icon sizes with badge sizes</dap-ds-typography>
  <dap-ds-stack direction="row" align="center">
    <dap-ds-badge size="sm" type="brand" icon="star-fill">
      Small
    </dap-ds-badge>
    <dap-ds-badge size="lg" type="brand" icon="star-fill">
      Large
    </dap-ds-badge>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Accessibility features

Badges support different accessibility modes based on their usage:

<>
<dap-ds-stack direction="column">
<div>
  <dap-ds-typography variant="h4">Static badges (default)</dap-ds-typography>
  <dap-ds-typography variant="body" style={{marginBottom: 'var(--dds-spacing-300)', color: 'var(--dds-text-neutral-subtle)'}}>
    For decorative or static content, uses role="img"
  </dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-badge type="neutral">Category</dap-ds-badge>
    <dap-ds-badge type="brand">Featured</dap-ds-badge>
    <dap-ds-badge type="info">Version 2.0</dap-ds-badge>
  </dap-ds-stack>
</div>

<div>
  <dap-ds-typography variant="h4">Live badges</dap-ds-typography>
  <dap-ds-typography variant="body" style={{marginBottom: 'var(--dds-spacing-300)', color: 'var(--dds-text-neutral-subtle)'}}>
    For dynamic content that should announce changes, uses role="status" and aria-live="polite"
  </dap-ds-typography>
  <dap-ds-stack direction="row">
    <dap-ds-badge type="positive" live icon="check-line">
      Processing Complete
    </dap-ds-badge>
    <dap-ds-badge type="warning" live icon="time-line">
      5 items pending
    </dap-ds-badge>
    <dap-ds-badge type="negative" live icon="alert-line">
      3 errors found
    </dap-ds-badge>
  </dap-ds-stack>
</div>
</dap-ds-stack>
</>
Real-World Patterns Status and Progress Indicators 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h4">Document Status</dap-ds-typography>
  <dap-ds-stack direction="row" justify="space-between" align="center">
    <dap-ds-stack direction="row" align="center">
      <dap-ds-typography variant="body" bold>Project Proposal.pdf</dap-ds-typography>
      <dap-ds-badge type="warning" icon="time-line">Under Review</dap-ds-badge>
    </dap-ds-stack>
    <dap-ds-typography variant="caption" style={{color: 'var(--dds-text-neutral-subtle)'}}>
      Updated 2 hours ago
    </dap-ds-typography>
  </dap-ds-stack>
  
  <dap-ds-stack direction="row" justify="space-between" align="center">
    <dap-ds-stack direction="row" align="center">
      <dap-ds-typography variant="body" bold>Budget Report.xlsx</dap-ds-typography>
      <dap-ds-badge type="positive" icon="check-line">Approved</dap-ds-badge>
    </dap-ds-stack>
    <dap-ds-typography variant="caption" style={{color: 'var(--dds-text-neutral-subtle)'}}>
      Approved yesterday
    </dap-ds-typography>
  </dap-ds-stack>
  
  <dap-ds-stack direction="row" justify="space-between" align="center">
    <dap-ds-stack direction="row" align="center">
      <dap-ds-typography variant="body" bold>Requirements.docx</dap-ds-typography>
      <dap-ds-badge type="negative" icon="close-line">Rejected</dap-ds-badge>
    </dap-ds-stack>
    <dap-ds-typography variant="caption" style={{color: 'var(--dds-text-neutral-subtle)'}}>
      Needs revision
    </dap-ds-typography>
  </dap-ds-stack>
</dap-ds-stack>
</div>
Notification and Alert Badges 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h4">System Notifications</dap-ds-typography>
  <dap-ds-stack>
    <dap-ds-stack direction="row" align="center">
      <dap-ds-badge type="info" live icon="mail-line">
        3 new messages
      </dap-ds-badge>
      <dap-ds-typography variant="body">
        You have unread messages from your team
      </dap-ds-typography>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" align="center">
      <dap-ds-badge type="warning" live icon="alert-line">
        Storage 85% full
      </dap-ds-badge>
      <dap-ds-typography variant="body">
        Consider upgrading your storage plan
      </dap-ds-typography>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" align="center">
      <dap-ds-badge type="positive" live icon="shield-check-line">
        Backup completed
      </dap-ds-badge>
      <dap-ds-typography variant="body">
        Last backup: Today at 3:00 AM
      </dap-ds-typography>
    </dap-ds-stack>
  </dap-ds-stack>
</dap-ds-stack>
</div>
Product Tags and Categories 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h4">Featured Products</dap-ds-typography>
  <div style={{display: 'grid', gap: 'var(--dds-spacing-400)', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))'}}>
    <div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-400)', borderRadius: 'var(--dds-radius-base)'}}>
      <dap-ds-stack>
        <dap-ds-stack direction="row" justify="space-between" align="start">
          <dap-ds-typography variant="h5">Premium Laptop</dap-ds-typography>
          <dap-ds-badge type="brand" icon="star-fill" size="sm">Featured</dap-ds-badge>
        </dap-ds-stack>
        <dap-ds-stack direction="row" wrap>
          <dap-ds-badge type="neutral" size="sm">Electronics</dap-ds-badge>
          <dap-ds-badge type="neutral" size="sm">Computers</dap-ds-badge>
          <dap-ds-badge type="positive" size="sm">Free Shipping</dap-ds-badge>
          <dap-ds-badge type="warning" size="sm">Limited Stock</dap-ds-badge>
        </dap-ds-stack>
        <dap-ds-typography variant="h4" style={{color: 'var(--dds-brand-600)'}}>$1,299</dap-ds-typography>
      </dap-ds-stack>
    </div>
    
    <div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-400)', borderRadius: 'var(--dds-radius-base)'}}>
      <dap-ds-stack>
        <dap-ds-stack direction="row" justify="space-between" align="start">
          <dap-ds-typography variant="h5">Wireless Headphones</dap-ds-typography>
          <dap-ds-badge type="negative" size="sm">Sale</dap-ds-badge>
        </dap-ds-stack>
        <dap-ds-stack direction="row" wrap>
          <dap-ds-badge type="neutral" size="sm">Audio</dap-ds-badge>
          <dap-ds-badge type="neutral" size="sm">Accessories</dap-ds-badge>
          <dap-ds-badge type="info" size="sm">New Arrival</dap-ds-badge>
        </dap-ds-stack>
        <dap-ds-stack direction="row" align="center">
          <dap-ds-typography variant="h4" style={{color: 'var(--dds-brand-600)'}}>$199</dap-ds-typography>
          <dap-ds-typography variant="body" style={{textDecoration: 'line-through', color: 'var(--dds-text-neutral-subtle)'}}>$299</dap-ds-typography>
        </dap-ds-stack>
      </dap-ds-stack>
    </div>
  </div>
</dap-ds-stack>
</div>
User Interface Status 
<div style={{border: 'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding: 'var(--dds-spacing-600)', borderRadius: 'var(--dds-radius-base)'}}>
<dap-ds-stack>
  <dap-ds-typography variant="h4">Service Status Dashboard</dap-ds-typography>
  <div style={{display: 'grid', gap: 'var(--dds-spacing-400)', gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))'}}>
    <dap-ds-stack direction="row" justify="space-between" align="center">
      <dap-ds-typography variant="body" bold>Authentication Service</dap-ds-typography>
      <dap-ds-badge type="positive" icon="check-line">Operational</dap-ds-badge>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" justify="space-between" align="center">
      <dap-ds-typography variant="body" bold>Payment Gateway</dap-ds-typography>
      <dap-ds-badge type="warning" icon="alert-line">Degraded</dap-ds-badge>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" justify="space-between" align="center">
      <dap-ds-typography variant="body" bold>Email Service</dap-ds-typography>
      <dap-ds-badge type="negative" icon="close-circle-line">Outage</dap-ds-badge>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" justify="space-between" align="center">
      <dap-ds-typography variant="body" bold>Database</dap-ds-typography>
      <dap-ds-badge type="positive" icon="check-line">Operational</dap-ds-badge>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" justify="space-between" align="center">
      <dap-ds-typography variant="body" bold>File Storage</dap-ds-typography>
      <dap-ds-badge type="info" icon="tools-line">Maintenance</dap-ds-badge>
    </dap-ds-stack>
    
    <dap-ds-stack direction="row" justify="space-between" align="center">
      <dap-ds-typography variant="body" bold>API Gateway</dap-ds-typography>
      <dap-ds-badge type="positive" icon="check-line">Operational</dap-ds-badge>
    </dap-ds-stack>
  </div>
</dap-ds-stack>
</div>
Custom Styling

The badge component supports extensive customization beyond the default variants. This section demonstrates practical styling techniques and advanced customization patterns.

Quick Customization with CSS Custom Properties

For simple customizations, use CSS custom properties directly on the component:

<dap-ds-stack direction="row">
<dap-ds-badge 
  type="neutral"
  style={{
    '--dds-badge-neutral-background': 'var(--dds-violet-200)',
    '--dds-badge-neutral-color': 'var(--dds-violet-900)',
    '--dds-badge-neutral-border-color': 'var(--dds-violet-600)',
  }}>
  Custom Colors
</dap-ds-badge>
<dap-ds-badge 
  type="brand" 
  icon="heart-fill"
  style={{
    '--dds-badge-border-radius': 'var(--dds-radius-rounded)',
    '--dds-badge-font-weight': 'var(--dds-font-weight-black)',
  }}>
  Rounded
</dap-ds-badge>
<dap-ds-badge 
  type="positive"
  style={{
    '--dds-badge-transition': 'all 0.3s ease',
    '--dds-badge-padding-sm': 'var(--dds-spacing-200) var(--dds-spacing-400)',
  }}>
  Extended Padding
</dap-ds-badge>
</dap-ds-stack>
Theme-Aware Styling

Create badges that automatically adapt to different themes:

<dap-ds-stack direction="row">
<dap-ds-badge 
  type="neutral"
  style={{
    '--dds-badge-neutral-background': 'var(--dds-background-neutral-strong)',
    '--dds-badge-neutral-color': 'var(--dds-text-neutral-inverted)',
    '--dds-badge-neutral-border-color': 'var(--dds-border-neutral-strong)',
  }}>
  High Contrast
</dap-ds-badge>
<dap-ds-badge 
  type="info"
  style={{
    '--dds-badge-info-background': 'transparent',
    '--dds-badge-info-color': 'var(--dds-informative-600)',
    '--dds-badge-info-border-color': 'var(--dds-informative-600)',
    '--dds-badge-border-width': 'var(--dds-border-width-thick)',
  }}>
  Outlined
</dap-ds-badge>
</dap-ds-stack>
Advanced CSS Classes

For more complex styling, use CSS classes that work with the component's CSS parts. Experiment with custom badge styling using CSS parts and custom properties. Try the presets below or create your own styles:

Select a presetGradient BadgeShadow BadgeGlow EffectScale EffectBorder Animate
Copy CSSFormat CSSResetLightDark
CSS Editor
Live Preview

Custom Badge

Implementation Notes Using Custom Styles in Your Project

The badge component uses Shadow DOM, which encapsulates styles. Here's how to implement custom styling effectively:

1. Shadow DOM Limitations

Note: Keyframe animations defined outside the component won't work due to Shadow DOM encapsulation. Use:

  • Transitions with hover states (✅ Works)
  • Transform effects (✅ Works)
  • CSS custom property changes (✅ Works)
  • External keyframe animations (❌ Won't work)
2. Accessibility with Live Badges

Use the live property for dynamic content that should announce changes:

<dap-ds-badge type="info" live icon="mail-line">
  3 new messages
</dap-ds-badge>
Importing 
import { DapDSBadge } from 'dap-design-system'
Importing React 
import { DapDSBadgeReact } from 'dap-design-system/react'
Tree-Shakeable Imports

For optimal bundle sizes, use the tree-shakeable import syntax:

import { DapDSBadge } from 'dap-design-system/components'
Attributes
PropertyTypeDefaultDescription
type'neutral', 'brand' , 'info' , 'positive' , 'warning' , 'negative''neutral'The type of the badge
size'sm', 'lg''sm'The size of the badge
iconstring, undefinedThe icon of the badge, this is a name of a built in icon
livebooleanfalseWhether the badge represents dynamic content that should announce changes
Slots
NameDescription
(default)The content of the badge.
iconThe icon of the badge.
Events

No custom events available.

CSS Parts
Part NameDescription
baseThe main container of the badge.
iconThe icon of the badge.
contentThe content of the badge.
icon-baseThe base of the icon.
How to Use CSS Parts

You can style CSS parts using the ::part() pseudo-element selector:

/* Target a specific part */
.my-custom-dap-ds-badge::part(base) {
  /* Your custom styles */
}

/* Target multiple parts */
.my-custom-dap-ds-badge::part(base),
.my-custom-dap-ds-badge::part(icon) {
  /* Shared styles */
}

Example usage:

<dap-ds-badge class="my-custom-dap-ds-badge">
  Badge
</dap-ds-badge>

.my-custom-dap-ds-badge::part(base) {
  border-radius: 12px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.

 CSS Custom Properties
Property NameDescription
--dds-badge-border-widthThe width of the badge's border (default: var(--dds-border-width-base))
--dds-badge-border-styleThe style of the badge's border (default: solid)
--dds-badge-border-radiusThe border radius of the badge (default: var(--dds-radius-base))
--dds-badge-font-weightThe font weight of the badge text (default: var(--dds-font-weight-bold))
--dds-badge-line-heightThe line height of the badge text (default: 1.2)
--dds-badge-transitionThe transition property for the badge (default: all 0.2s ease-in-out)
--dds-badge-padding-smThe padding of the small badge (default: var(--dds-spacing-100) var(--dds-spacing-200))
--dds-badge-padding-lgThe padding of the large badge (default: var(--dds-spacing-100) var(--dds-spacing-300))
--dds-badge-font-size-smThe font size of the small badge (default: var(--dds-font-xs))
--dds-badge-font-size-lgThe font size of the large badge (default: var(--dds-font-sm))
--dds-badge-neutral-border-colorThe border color of the neutral badge (default: var(--dds-border-neutral-base))
--dds-badge-neutral-backgroundThe background color of the neutral badge (default: var(--dds-background-neutral-medium))
--dds-badge-neutral-colorThe text color of the neutral badge (default: var(--dds-text-neutral-subtle))
--dds-badge-brand-border-colorThe border color of the brand badge (default: var(--dds-border-brand-base))
--dds-badge-brand-backgroundThe background color of the brand badge (default: var(--dds-background-brand-medium))
--dds-badge-brand-colorThe text color of the brand badge (default: var(--dds-text-brand-subtle))
--dds-badge-info-border-colorThe border color of the info badge (default: var(--dds-border-informative-base))
--dds-badge-info-backgroundThe background color of the info badge (default: var(--dds-background-informative-medium))
--dds-badge-info-colorThe text color of the info badge (default: var(--dds-text-informative-subtle))
--dds-badge-positive-border-colorThe border color of the positive badge (default: var(--dds-border-positive-base))
--dds-badge-positive-backgroundThe background color of the positive badge (default: var(--dds-background-positive-medium))
--dds-badge-positive-colorThe text color of the positive badge (default: var(--dds-text-positive-subtle))
--dds-badge-warning-border-colorThe border color of the warning badge (default: var(--dds-border-warning-subtle))
--dds-badge-warning-backgroundThe background color of the warning badge (default: var(--dds-background-warning-medium))
--dds-badge-warning-colorThe text color of the warning badge (default: var(--dds-text-warning-subtle))
--dds-badge-negative-border-colorThe border color of the negative badge (default: var(--dds-border-negative-base))
--dds-badge-negative-backgroundThe background color of the negative badge (default: var(--dds-background-negative-medium))
--dds-badge-negative-colorThe text color of the negative badge (default: var(--dds-text-negative-subtle))
How to Use CSS Custom Properties

CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:

Method 1: Inline styles (Quick customization)

<dap-ds-badge
  style="--dds-badge-border-width: value; --dds-badge-border-style: value;">
  Badge
</dap-ds-badge>

Method 2: CSS classes (Reusable styles)

.my-custom-dap-ds-badge {
  --dds-badge-border-width: value;
  --dds-badge-border-style: value;
  --dds-badge-border-radius: value;
}

<dap-ds-badge class="my-custom-dap-ds-badge">
  Badge
</dap-ds-badge>

Method 3: Global theme customization

/* Apply to all instances */
dap-ds-badge {
  --dds-badge-border-width: value;
  --dds-badge-border-style: value;
}

CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.