> Markdown version of [Badge](https://vaadin.com/docs/v24/components/badge). Section index: [llms.txt](https://vaadin.com/docs/v24/components/llms.txt)
# Badge
Badges are colored text elements containing small bits of information. They’re used for labeling content, displaying metadata and/or highlighting information.
**Lit** — `badge-basic.ts`
```html
PendingConfirmedWarningDeniedOn hold
```
**Flow** — `BadgeBasic.java`
```java
Span pending = new Span("Pending");
pending.getElement().getThemeList().add("badge");
Span confirmed = new Span("Confirmed");
confirmed.getElement().getThemeList().add("badge success");
Span warning = new Span("Warning");
warning.getElement().getThemeList().add("badge warning");
Span denied = new Span("Denied");
denied.getElement().getThemeList().add("badge error");
Span onHold = new Span("On hold");
onHold.getElement().getThemeList().add("badge contrast");
```
**React** — `badge-basic.tsx`
```tsx
{/* Since a native span element does not know about the theme attribute, as a workaround, you
can use the spread operator to pass the theme attribute to the span element. */}
PendingConfirmedWarningDeniedOn hold
```
> **Note: Import styles**
>
> Badge is a set of CSS classes rather than a web / Flow component. The Badge-specific CSS classes are available as part of the Lumo theme. To use these classes in your application, enable them in your theme’s `theme.json`:
>
> ```json
> {
> "lumoImports": [<...>, "badge"]
> }
> ```
>
> The `theme.json` is located in the theme folder at `/src/main/frontend/themes//theme.json`.
## Label
Badges should contain a label. Labels should be clear, concise, and written using sentence case. Aim for 1 to 2 words.
## Icons
Badges can contain icons as well as text. Icons can be placed on either side of the text.
**Lit** — `badge-icons.ts`
```html
PendingConfirmedWarningDeniedOn holdPendingConfirmedWarningDeniedOn hold
```
**Flow** — `BadgeIcons.java`
```java
// Icon before text
Span pending1 = new Span(createIcon(VaadinIcon.CLOCK),
new Span("Pending"));
pending1.getElement().getThemeList().add("badge");
// Icon after text
Span pending2 = new Span(new Span("Pending"),
createIcon(VaadinIcon.CLOCK));
pending2.getElement().getThemeList().add("badge");
...
private Icon createIcon(VaadinIcon vaadinIcon) {
Icon icon = vaadinIcon.create();
icon.getStyle().set("padding", "var(--lumo-space-xs)");
return icon;
}
```
**React** — `badge-icons.tsx`
```tsx
PendingConfirmedWarningDeniedOn holdPendingConfirmedWarningDeniedOn hold
```
> **Note: Use icons sparingly**
>
> The benefit of using icons should be weighed against the visual noise it adds.
### Icon-Only
Badges can also be used with icons without a label. For accessibility, a tooltip and `aria-label` attribute is recommended to ensure that all users can identify their meaning.
**Lit** — `badge-icons-only.ts`
```html
```
**Flow** — `BadgeIconsOnly.java`
```java
Icon confirmed = createIcon(VaadinIcon.CHECK, "Confirmed");
confirmed.getElement().getThemeList().add("badge success");
Icon cancelled = createIcon(VaadinIcon.CLOSE_SMALL, "Cancelled");
cancelled.getElement().getThemeList().add("badge error");
...
private Icon createIcon(VaadinIcon vaadinIcon, String label) {
Icon icon = vaadinIcon.create();
icon.getStyle().set("padding", "var(--lumo-space-xs");
// Accessible label
icon.getElement().setAttribute("aria-label", label);
// Tooltip
icon.getElement().setAttribute("title", label);
return icon;
}
```
**React** — `badge-icons-only.tsx`
```tsx
```
Icon-only badges should primarily be used for common recurring content with highly standardized, universally understood icons (such as a checkmark for "*yes*"), and for content that’s repeated, for example in lists and tables.
**Lit** — `badge-icons-only-table.ts`
```typescript
const renderBoolean: GridColumnBodyLitRenderer = (item, _model, column) => {
let icon: string;
let title: string;
let theme: string;
if (item[column.id as keyof UserPermissions]) {
icon = 'vaadin:check';
title = 'Yes';
theme = 'success';
} else {
icon = 'vaadin:close-small';
title = 'No';
theme = 'error';
}
return html`
`;
};
return html`
`;
```
**Flow** — `BadgeIconsOnlyTable.java`
```java
grid.addColumn(UserPermissions::getName).setHeader("Name");
grid.addComponentColumn(userPermissions -> createPermissionIcon(
userPermissions.getView())).setHeader("View");
grid.addComponentColumn(userPermissions -> createPermissionIcon(
userPermissions.getComment())).setHeader("Comment");
grid.addComponentColumn(userPermissions -> createPermissionIcon(
userPermissions.getEdit())).setHeader("Edit");
...
private Icon createPermissionIcon(boolean hasPermission) {
Icon icon;
if (hasPermission) {
icon = createIcon(VaadinIcon.CHECK, "Yes");
icon.getElement().getThemeList().add("badge success");
} else {
icon = createIcon(VaadinIcon.CLOSE_SMALL, "No");
icon.getElement().getThemeList().add("badge error");
}
return icon;
}
private Icon createIcon(VaadinIcon vaadinIcon, String label) {
Icon icon = vaadinIcon.create();
icon.getStyle().set("padding", "var(--lumo-space-xs");
// Accessible label
icon.getElement().setAttribute("aria-label", label);
// Tooltip
icon.getElement().setAttribute("title", label);
return icon;
}
```
**React** — `badge-icons-only-table.tsx`
```tsx
const renderBadge = ({
item,
original: column,
}: {
item: any;
original: GridColumnElement;
}) => {
let icon;
let title;
let theme;
if (item[column.id]) {
icon = 'vaadin:check';
title = 'Yes';
theme = 'success';
} else {
icon = 'vaadin:close-small';
title = 'No';
theme = 'error';
}
return (
);
};
return (
);
```
## Theme Variants
Badge features theme variants for different sizes, colors, and shapes. You can combine any theme variants together.
### Size
Badges have two different sizes you can use: the default (normal) and `small`. Use the `small` theme variant to make a badge smaller, for example when space is limited or for compact parts of the UI.
**Lit** — `badge-size.ts`
```html
PendingConfirmedWarningDeniedOn hold
```
**Flow** — `BadgeSize.java`
```java
Span pending = new Span("Pending");
pending.getElement().getThemeList().add("badge small");
Span confirmed = new Span("Confirmed");
confirmed.getElement().getThemeList().add("badge success small");
Span warning = new Span("Warning");
warning.getElement().getThemeList().add("badge warning small");
Span denied = new Span("Denied");
denied.getElement().getThemeList().add("badge error small");
Span onHold = new Span("On hold");
onHold.getElement().getThemeList().add("badge contrast small");
```
**React** — `badge-size.tsx`
```tsx
PendingConfirmedWarningDeniedOn hold
```
### Color
Badges have four different color variants: default, `success`, `error`, and `contrast`. The color variants can be paired with the `primary` theme variant for additional emphasis.
**Lit** — `badge-color.ts`
```html
PendingConfirmedWarningDeniedOn holdPendingConfirmedWarningDeniedOn hold
```
**Flow** — `BadgeColor.java`
```java
// Default variant
Span pending = new Span("Pending");
pending.getElement().getThemeList().add("badge");
// Primary variant
Span pendingPrimary = new Span("Pending");
pendingPrimary.getElement().getThemeList().add("badge primary");
```
**React** — `badge-color.tsx`
```tsx
PendingConfirmedWarningDeniedOn holdPendingConfirmedWarningDeniedOn hold
```
| Variant | Theme name | Usage recommendations |
| -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Normal | | Default style. Recommended for informational messages. This style may be confused with a Button or link. |
| Success | `success` | Highlight positive outcomes, such as when a task or operation is completed. |
| Warning | `warning` | Communicates caution or potential issues that require user attention. |
| Error | `error` | Use the error theme variant to communicate alerts and failures. |
| Contrast | `contrast` | A high-contrast version that improves legibility and distinguishes the badge from the rest of the UI. Recommended for neutral badges (that don’t communicate success or errors). |
| Primary | `primary` | Used for important information and/or to draw more attention to your badge. Can be combined with all other theme variants. |
> **Note: Accessibility**
>
> Assistive technologies, such as screen readers, interpret badges solely based on their content. Without proper context, they may end up confusing the user. If you are using colors and icons to convey information, provide the same info via `aria-label` to ensure that screen readers can interpret the information.
### Shape
Applying the `pill` theme variant produces a badge with rounded corners. It can aid in making badges and buttons more distinct from one another.
**Lit** — `badge-shape.ts`
```html
PendingConfirmedWarningDeniedOn hold
```
**Flow** — `BadgeShape.java`
```java
Span pending = new Span("Pending");
pending.getElement().getThemeList().add("badge pill");
Span confirmed = new Span("Confirmed");
confirmed.getElement().getThemeList().add("badge success pill");
Span warning = new Span("Warning");
warning.getElement().getThemeList().add("badge warning pill");
Span denied = new Span("Denied");
denied.getElement().getThemeList().add("badge error pill");
Span onHold = new Span("On hold");
onHold.getElement().getThemeList().add("badge contrast pill");
```
**React** — `badge-shape.tsx`
```tsx
PendingConfirmedWarningDeniedOn hold
```
## Use Cases
### Highlighting and Distinguishing Information
A typical use case for badges is to highlight an item’s status, for example in a Grid.
**Lit** — `badge-highlight.ts`
```typescript
return html`
(
({ due }) => html`${dateFormatter.format(new Date(due))}`,
[]
)}
>(({ status }) => {
let title: string;
let theme: string;
switch (status) {
case ReportStatus.COMPLETED:
title = 'Completed';
theme = 'success';
break;
case ReportStatus.IN_PROGRESS:
title = 'In progress';
theme = '';
break;
case ReportStatus.CANCELLED:
title = 'Cancelled';
theme = 'error';
break;
default:
title = 'On hold';
theme = 'contrast';
break;
}
return html`${title}`;
}, [])}
>
`;
```
**Flow** — `BadgeHighlight.java`
```java
grid.addComponentColumn(report -> createStatusBadge(report.getStatus()))
.setHeader("Status");
...
private Span createStatusBadge(String status) {
String theme;
switch (status) {
case "In progress":
theme = "badge primary";
break;
case "Completed":
theme = "badge success primary";
break;
case "Cancelled":
theme = "badge error primary";
break;
default:
theme = "badge contrast primary";
break;
}
Span badge = new Span(status);
badge.getElement().getThemeList().add(theme);
return badge;
}
```
**React** — `badge-highlight.tsx`
```tsx
function renderDueDate({ item: report }: { item: Report }) {
return {dateFormatter.format(new Date(report.due))};
}
function renderStatus({ item: report }: { item: Report }) {
let title: string;
let theme: string;
switch (report.status) {
case ReportStatus.COMPLETED:
title = 'Completed';
theme = 'success';
break;
case ReportStatus.IN_PROGRESS:
title = 'In progress';
theme = '';
break;
case ReportStatus.CANCELLED:
title = 'Cancelled';
theme = 'error';
break;
default:
title = 'On hold';
theme = 'contrast';
break;
}
return {title};
}
function Example() {
const items = useSignal([]);
useEffect(() => {
getReports().then((reports) => {
items.value = reports as Report[];
});
}, []);
return (
);
}
```
They are also often used for displaying metadata tags.
### Interactive Content
Badges can house interactive content such as Anchors and Buttons. For example, Badges that highlight active filters might contain a "Clear" Button which removes the associated filter.
**Lit** — `badge-interactive.ts`
```typescript
return html`
${repeat(
this.selectedProfessions,
(profession) => profession,
(profession) => html`
${profession}
`
)}
`;
```
**Flow** — `BadgeInteractive.java`
```java
HorizontalLayout badges = new HorizontalLayout();
badges.getStyle().set("flex-wrap", "wrap");
ComboBox comboBox = new ComboBox<>("Profession");
comboBox.setItems(DataService.getProfessions());
comboBox.addValueChangeListener(e -> {
Span filterBadge = createFilterBadge(e.getValue());
badges.add(filterBadge);
});
...
private Span createFilterBadge(String profession) {
Button clearButton = new Button(VaadinIcon.CLOSE_SMALL.create());
clearButton.addThemeVariants(ButtonVariant.LUMO_CONTRAST,
ButtonVariant.LUMO_TERTIARY_INLINE);
clearButton.getStyle().set("margin-inline-start",
"var(--lumo-space-xs)");
// Accessible button name
clearButton.getElement().setAttribute("aria-label",
"Clear filter: " + profession);
// Tooltip
clearButton.getElement().setAttribute("title",
"Clear filter: " + profession);
Span badge = new Span(new Span(profession), clearButton);
badge.getElement().getThemeList().add("badge contrast pill");
// Add handler for removing the badge
clearButton.addClickListener(event -> {
badge.getElement().removeFromParent();
});
return badge;
}
```
**React** — `badge-interactive.tsx`
```tsx
return (
{selectedProfessions.value.map((profession) => (
{profession}
))}
);
```
### Counter
Badges can be used as counters, for example to show the number of unread/new messages, selection count, etc.
**Lit** — `badge-counter.ts`
```html
Inbox
12
Important
3
Spam
45
Archive
23
```
**Flow** — `BadgeCounter.java`
```java
Tabs tabs = new Tabs(createTab("Inbox", 12), createTab("Important", 3),
createTab("Spam", 45), createTab("Archive", 23));
...
private static Tab createTab(String labelText, int messageCount) {
Span label = new Span(labelText);
Span counter = new Span(String.valueOf(messageCount));
counter.getElement().getThemeList().add("badge pill small contrast");
counter.getStyle().set("margin-inline-start", "var(--lumo-space-s)");
// Accessible badge label
String counterLabel = String.format("%d unread messages", messageCount);
counter.getElement().setAttribute("aria-label", counterLabel);
counter.getElement().setAttribute("title", counterLabel);
return new Tab(label, counter);
}
```
**React** — `badge-counter.tsx`
```tsx
Inbox
12
Important
3
Spam
45
Archive
23
```
Assistive technologies, such as screen readers, interpret badges solely based on their content. Without proper context, they may end up confusing the user. To provide context for people using screen readers, set the badge’s `aria-label` attribute.
## Best Practices
### Badge vs Button
Badges and Buttons are similar in appearance. This might lead users to think that badges are interactive.
Placement, language, shape, and color can all help mitigate any confusion. First, badges shouldn’t be labeled with active verbs. They aren’t actions, but rather static text/content. Second, avoid placing badges directly next to Buttons, in particular if they are using similar themes. The `pill` theme variant may aid in making badges and Buttons more distinct from one another.
`69AF8882-CA67-4AB8-BF9F-69A1EA6CE84C`