In progress

Badge

Badges are used to indicate a notification, item count, or other contextual information related to a navigation destination.

• Figma
• Storybook
• Edit this page
• Create a new issue

3

Code example

import { Badge } from '@yleisradio/yds-components-react';

<Badge variant="primary" size="xl">3</Badge>

Why to Use

The Badge component visually indicates a status, count, or notification associated with another UI element. It helps users quickly identify new information, pending actions, or system alerts without needing to open the full view. They are typically displayed inside or attached to another component, such as an icon, button, or tab.

Badges are commonly used in navigation or profile contexts — for example, to show the number of unread messages, notifications, or active tasks. They are non-interactive and rely on their placement and appearance to convey meaning clearly.

When to Use

Use Badge when you want to draw attention to updates, counts, or statuses related to another UI element.

Do

• Attach directly to a relevant component (e.g. icon, button, tab).
• Use it to display numeric counts (e.g., messages, tasks) or state indicators.
• Use ARIA attributes (e.g., aria-label, aria-live) to make changes accessible.
• Choose a size that keeps the count legible relative to the parent.

Don’t

• Don’t use Badge as an interactive control.
• Avoid animations or flashing that may cause distraction or accessibility issues.
• Don’t display text or numbers too small.

Key Props

Use the following props to customize the Badge component to fit your needs.

size

Controls the visual dimensions and typography. Smaller sizes (sm, md) are suited to minimal indicators (dots); larger sizes (lg, xl) accommodate numeric content.

Value	Example	Description
sm		Tiny status indicator without text. Used in upper right corner of navigation item.
md		Small status/count indicator without text. Used in upper right corner of navigation item.
lg	3	Default size.
xl	12	Prominent counts or emphasis. For inline use.

Code example

<Badge size="sm" />
<Badge size="md" />
<Badge size="lg">3</Badge>
<Badge size="xl">12</Badge>

color

Defines semantic color scheme.

Value	Example	Description
default	4	Standard action background; generic counts.
negative	2	Neutral/subtle emphasis; lower visual weight.
highlight	12	High-attention feedback. Use sparingly.

Code example

<Badge color="default" size="lg">4</Badge>
<Badge color="negative" size="lg">2</Badge>
<Badge color="highlight" size="lg">12</Badge>

variant

Alters structural presentation (border & padding). primary is a filled pill; secondary applies an outline for large sizes (lg, xl).

Value	Example	Description
primary	12	Filled default style.
secondary	12	Outline improves contrast against background but reduces badge size

Code example

<Badge variant="primary" size="lg">3</Badge>
<Badge variant="secondary" size="lg">3</Badge>
<Badge variant="primary" size="xl">12</Badge>
<Badge variant="secondary" size="xl">12</Badge>

Accessibility

• Use aria-label when numeric value or color alone lacks context (e.g. <Badge aria-label="7 unread messages">7</Badge>).
• Keep numbers short; truncate or summarize large counts (e.g. 99+).

Code example

<Badge size="lg" aria-label="7 unread messages">7</Badge>

See more examples in Storybook

API Reference

Props

The Badge component accepts all standard HTML <span> attributes in addition to the following props:

Prop	Type	Required	Default	Description
size	BadgeSizeProp	No	'lg'	Size of the Badge
children	React.ReactNode	No	—
color	BadgeColorProp	No	'default'	Color of the Badge
variant	BadgeVariantProp	No	'primary'	Visual presentation of the Badge

Type Definitions

export type BadgeSizeProp = 'xl' | 'lg' | 'md' | 'sm';
export type BadgeColorProp = 'default' | 'negative' | 'highlight';
export type BadgeVariantProp = 'primary' | 'secondary';

export interface BadgeDSProps {
  size?: BadgeSizeProp;
  children?: React.ReactNode;
  color?: BadgeColorProp;
  variant?: BadgeVariantProp;
}

export type BadgeProps = HTMLAttributes<HTMLSpanElement> & BadgeDSProps;

Related Components

• Button – Badges often attach to buttons to show counts.
• NavigationTab – Use Badges to show per-tab notification or item counts.
• Tag – Static keyword label without counts.
• TagLink – Interactive keyword navigation.
• TagFilter – Removable filter chips.