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-full)',
    '--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:

<dap-ds-stack direction="row">
<dap-ds-badge 
  class="custom-badge-gradient"
  type="brand">
  Gradient Badge
</dap-ds-badge>
<dap-ds-badge 
  class="custom-badge-shadow"
  type="neutral">
  Shadow Badge
</dap-ds-badge>
  <dap-ds-badge 
  class="badge-glow"
  type="positive" 
  icon="check-line">
  Hover Glow Effect
</dap-ds-badge>
<dap-ds-badge 
  class="badge-scale"
  type="warning"
  icon="time-line">
  Hover Scale Effect
</dap-ds-badge>
<dap-ds-badge 
  class="badge-border-animate"
  type="info"
  icon="information-line">
  Hover Border Effect
</dap-ds-badge>
</dap-ds-stack>

.custom-badge-gradient {
    --dds-badge-brand-background: linear-gradient(135deg, var(--dds-brand-600), var(--dds-violet-600));
    --dds-badge-brand-color: var(--dds-white-100);
    --dds-badge-border-radius: var(--dds-radius-large);
    --dds-badge-transition: all 0.3s ease;
  }
  
  .custom-badge-shadow::part(base) {
    box-shadow: 0 var(--dds-spacing-200) var(--dds-spacing-400) rgba(0, 0, 0, 0.15);
    transition: box-shadow 0.3s ease;
  }
  
  .custom-badge-shadow::part(base):hover {
    box-shadow: 0 var(--dds-spacing-400) var(--dds-spacing-800) rgba(0, 0, 0, 0.2);
  }

  .badge-glow::part(base) {
    position: relative;
    box-shadow: 0 0 var(--dds-spacing-300) var(--dds-positive-300);
    transition: box-shadow 0.3s ease;
  }
  
  .badge-glow::part(base):hover {
    box-shadow: 0 0 var(--dds-spacing-500) var(--dds-positive-400);
  }
  
  .badge-scale {
    --dds-badge-transition: all 0.2s ease;
  }
  
  .badge-scale::part(base):hover {
    transform: scale(1.05);
  }
  
  .badge-border-animate {
    --dds-badge-transition: all 0.3s ease;
    --dds-badge-border-width: var(--dds-border-width-base);
  }
  
  .badge-border-animate::part(base):hover {
    --dds-badge-border-width: var(--dds-border-width-thick);
  }
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. CSS Custom Properties (Recommended)

Use the component's CSS custom properties for reliable customizations:

.my-custom-badge {
  --dds-badge-neutral-background: var(--dds-violet-200);
  --dds-badge-neutral-color: var(--dds-violet-900);
  --dds-badge-border-radius: var(--dds-radius-full);
  --dds-badge-transition: all 0.3s ease;
}
2. CSS Parts for Advanced Styling

Target specific parts using ::part() pseudo-element:

.my-hover-badge::part(base) {
  transition: transform 0.2s ease;
}

.my-hover-badge::part(base):hover {
  transform: scale(1.05);
}
3. 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)
4. 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>
5. Best Practices
  • Test hover effects on touch devices
  • Ensure sufficient color contrast for custom themes
  • Use semantic badge types that match your content
  • Consider reduced motion preferences for animations
Importing 
import { DapDSBadge } from 'dap-design-system/dist/dds'
Importing React 
import { DapDSBadgeReact } from 'dap-design-system/dist/react'
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.
CSS Custom Properties
Property NameDescription
--dds-badge-border-widthThe width of the badge's border. Default is the design system's base border width.
--dds-badge-border-styleThe style of the badge's border. Default is solid.
--dds-badge-border-radiusThe border radius of the badge. Default is the design system's base radius.
--dds-badge-font-weightThe font weight of the badge text. Default is bold.
--dds-badge-line-heightThe line height of the badge text. Default is 1.2.
--dds-badge-transitionThe transition property for the badge. Default is 'all 0.2s ease-in-out'.
--dds-badge-padding-smThe padding of the small badge. Default is the design system's spacing-100 and spacing-200.
--dds-badge-padding-lgThe padding of the large badge. Default is the design system's spacing-100 and spacing-300.
--dds-badge-font-size-smThe font size of the small badge. Default is the design system's font-xs.
--dds-badge-font-size-lgThe font size of the large badge. Default is the design system's font-sm.
--dds-badge-neutral-border-colorThe border color of the neutral badge. Default is the design system's border-neutral-base.
--dds-badge-neutral-backgroundThe background color of the neutral badge. Default is the design system's background-neutral-medium.
--dds-badge-neutral-colorThe text color of the neutral badge. Default is the design system's text-neutral-subtle.
--dds-badge-brand-border-colorThe border color of the brand badge. Default is the design system's border-brand-base.
--dds-badge-brand-backgroundThe background color of the brand badge. Default is the design system's background-brand-medium.
--dds-badge-brand-colorThe text color of the brand badge. Default is the design system's text-brand-subtle.
--dds-badge-info-border-colorThe border color of the info badge. Default is the design system's border-informative-base.
--dds-badge-info-backgroundThe background color of the info badge. Default is the design system's background-informative-medium.
--dds-badge-info-colorThe text color of the info badge. Default is the design system's text-informative-subtle.
--dds-badge-positive-border-colorThe border color of the positive badge. Default is the design system's border-positive-base.
--dds-badge-positive-backgroundThe background color of the positive badge. Default is the design system's background-positive-medium.
--dds-badge-positive-colorThe text color of the positive badge. Default is the design system's text-positive-subtle.
--dds-badge-warning-border-colorThe border color of the warning badge. Default is the design system's border-warning-subtle.
--dds-badge-warning-backgroundThe background color of the warning badge. Default is the design system's background-warning-medium.
--dds-badge-warning-colorThe text color of the warning badge. Default is the design system's text-warning-subtle.
--dds-badge-negative-border-colorThe border color of the negative badge. Default is the design system's border-negative-base.
--dds-badge-negative-backgroundThe background color of the negative badge. Default is the design system's background-negative-medium.
--dds-badge-negative-colorThe text color of the negative badge. Default is the design system's text-negative-subtle.