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.
✅ 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)
Different types of badges for different statuses
Choose badge sizes based on context and visual hierarchy. Small badges work well for compact layouts, while large badges are more prominent:
Badges can include icons to provide additional visual context:
Badges support different accessibility modes based on their usage:
The badge component supports extensive customization beyond the default variants. This section demonstrates practical styling techniques and advanced customization patterns.
For simple customizations, use CSS custom properties directly on the component:
Create badges that automatically adapt to different themes:
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:
Custom Badge
The badge component uses Shadow DOM, which encapsulates styles. Here's how to implement custom styling effectively:
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)
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>
Import the component by its own subpath. This registers <dap-ds-badge> (and the
components it renders internally) and lets your bundler include only what you use:
import 'dap-design-system/components/badge'
Need a reference to the class (e.g. to register it manually or extend it)? The same subpath default-exports it:
import DapDSBadge from 'dap-design-system/components/badge'
Register the whole library at once — convenient, but pulls every component into your bundle:
import 'dap-design-system'
import { DapDSBadgeReact } from 'dap-design-system/react'
| Property | Type | Default | Description |
|---|---|---|---|
type | 'neutral', 'brand' , 'info' , 'positive' , 'warning' , 'negative' | 'neutral' | The type of the badge |
icon | string, undefined | The icon of the badge, this is a name of a built in icon | |
live | boolean | false | Whether the badge represents dynamic content that should announce changes |
size | 'sm', 'lg' | The size of the badge. Default is sm. | |
sizeMap | string | Responsive size map (e.g. "md:lg"). |
| Name | Description |
|---|---|
(default) | The content of the badge. |
icon | The icon of the badge. |
No custom events available.
| Part Name | Description |
|---|---|
base | The main container of the badge. |
icon | The icon of the badge. |
content | The content of the badge. |
icon-base | The base of the icon. |
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.
| Property Name | Description |
|---|---|
--dds-badge-border-width | The width of the badge's border (default: var(--dds-border-width-base)) |
--dds-badge-border-style | The style of the badge's border (default: solid) |
--dds-badge-border-radius | The border radius of the badge (default: var(--dds-radius-base)) |
--dds-badge-font-weight | The font weight of the badge text (default: var(--dds-font-weight-bold)) |
--dds-badge-line-height | The line height of the badge text (default: 1.2) |
--dds-badge-transition | The transition property for the badge (default: all 0.2s ease-in-out) |
--dds-badge-padding-sm | The padding of the small badge (default: var(--dds-spacing-100) var(--dds-spacing-200)) |
--dds-badge-padding-lg | The padding of the large badge (default: var(--dds-spacing-100) var(--dds-spacing-300)) |
--dds-badge-font-size-sm | The font size of the small badge (default: var(--dds-font-xs)) |
--dds-badge-font-size-lg | The font size of the large badge (default: var(--dds-font-sm)) |
--dds-badge-neutral-border-color | The border color of the neutral badge (default: var(--dds-border-neutral-base)) |
--dds-badge-neutral-background | The background color of the neutral badge (default: var(--dds-background-neutral-medium)) |
--dds-badge-neutral-color | The text color of the neutral badge (default: var(--dds-text-neutral-subtle)) |
--dds-badge-brand-border-color | The border color of the brand badge (default: var(--dds-border-brand-base)) |
--dds-badge-brand-background | The background color of the brand badge (default: var(--dds-background-brand-medium)) |
--dds-badge-brand-color | The text color of the brand badge (default: var(--dds-text-brand-subtle)) |
--dds-badge-info-border-color | The border color of the info badge (default: var(--dds-border-informative-base)) |
--dds-badge-info-background | The background color of the info badge (default: var(--dds-background-informative-medium)) |
--dds-badge-info-color | The text color of the info badge (default: var(--dds-text-informative-subtle)) |
--dds-badge-positive-border-color | The border color of the positive badge (default: var(--dds-border-positive-base)) |
--dds-badge-positive-background | The background color of the positive badge (default: var(--dds-background-positive-medium)) |
--dds-badge-positive-color | The text color of the positive badge (default: var(--dds-text-positive-subtle)) |
--dds-badge-warning-border-color | The border color of the warning badge (default: var(--dds-border-warning-subtle)) |
--dds-badge-warning-background | The background color of the warning badge (default: var(--dds-background-warning-medium)) |
--dds-badge-warning-color | The text color of the warning badge (default: var(--dds-text-warning-subtle)) |
--dds-badge-negative-border-color | The border color of the negative badge (default: var(--dds-border-negative-base)) |
--dds-badge-negative-background | The background color of the negative badge (default: var(--dds-background-negative-medium)) |
--dds-badge-negative-color | The text color of the negative badge (default: var(--dds-text-negative-subtle)) |
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.
