Skip to content
Components, switch product

Badge

<gui-badge> is a short label for a status or a count, such as “Paid” or “3 new messages”. Its children are the text. It sits inline with the text around it, in the same intents as the alert.

Invoice 1042 Paid

Code of the example above
BadgeBasic.tsx
import { GuiBadge } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function BadgeBasic() {
return (
<p>
Invoice 1042 <GuiBadge variant="success">Paid</GuiBadge>
</p>
);
}

The element’s entry point is @golemui/gui-components/badge, which registers <gui-badge> and nothing else. To install the package and load the stylesheet, see Installation.

The @golemui/gui-components/react components have typed props and an on* prop for each event. React 18 or later.

BadgeExample.tsx
import { GuiBadge } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function BadgeExample() {
return (
<GuiBadge
variant="success"
>
Paid
</GuiBadge>
);
}

Write the text inside it. Keep it short: a badge stays on one line.

Properties

Property Type Default Description
variant GuiBadgeVariant – The intent the badge shows. Without one it is neutral. It reflects, for the stylesheet: set from a framework as a property, it still colors the badge.

variant sets the intent: none for the neutral badge, info, success, warning or error. The color is not the only cue: the text says what it means.

Draft New Paid Due soon Overdue

Code of the example above
BadgeVariants.tsx
import { GuiBadge } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function BadgeVariants() {
return (
<p>
<GuiBadge>Draft</GuiBadge> <GuiBadge variant="info">New</GuiBadge>{' '}
<GuiBadge variant="success">Paid</GuiBadge>{' '}
<GuiBadge variant="warning">Due soon</GuiBadge>{' '}
<GuiBadge variant="error">Overdue</GuiBadge>
</p>
);
}

A badge has no role: screen readers read it as part of the sentence around it, and they don’t read its color. Write a count with what it counts, “3 new messages” rather than “3”, so the text makes sense when it is read aloud.

Billing Action needed

Inbox 3 new messages

Code of the example above
BadgeInText.tsx
import { GuiBadge } from '@golemui/gui-components/react';
import '@golemui/gui-components/index.css';
export function BadgeInText() {
return (
<>
<p>
Billing <GuiBadge variant="warning">Action needed</GuiBadge>
</p>
<p>
Inbox <GuiBadge variant="info">3 new messages</GuiBadge>
</p>
</>
);
}

<gui-badge> renders nothing of its own. It is your text, styled:

gui-badge
<gui-badge variant="success">Paid</gui-badge>

The badge has no classes. Style it by tag, and each variant by its attribute, which the element reflects when you set the property from a framework:

SelectorPart
gui-badgeThe badge, in every style.
gui-badge[variant='info']The info badge.
gui-badge[variant='error']The error badge.

The badge is an inline flex box, display: inline-flex, and still hides with the hidden attribute.

The badge reads these design tokens. Set them on :root to change every badge, or on any element to change the badges inside it:

TokenWhat it styles
--gui-badge-heightThe smallest height of the badge. 1.25rem by default.
--gui-badge-radiusThe corner radius. var(--gui-radius-full) by default: a pill.
--gui-badge-font-sizeThe text size. var(--gui-font-xs) by default.
--gui-space-2The space at the start and end of the badge.
--gui-bg-surface-hover, --gui-border-default, --gui-text-defaultThe background, border and text of the neutral badge.
--gui-intent-info-bg, --gui-intent-info, --gui-intent-info-textThe background, border and text of info.
--gui-intent-success-bg, --gui-intent-success, --gui-intent-success-textThe background, border and text of success.
--gui-intent-warning-bg, --gui-intent-warning, --gui-intent-warning-textThe background, border and text of warning.
--gui-intent-error-bg, --gui-intent-error, --gui-intent-error-textThe background, border and text of error.

The intent tokens are listed in Tokens.

styles.css
/* Square badges in the orders table. */
.orders {
--gui-badge-radius: var(--gui-radius-sm);
}

To restyle beyond the tokens, see Overriding styles; for dark mode and the Clay theme, see Themes and dark mode.

  • No role. The badge is text. Screen readers read it with the text around it, in reading order, and don’t announce it on its own.
  • Contrast. In every variant, the text reaches a 4.5:1 contrast with the badge’s fill.
  • Color. Each variant has its own colors, but screen readers don’t read them. Put the meaning in the text: “Overdue”, not a red badge with a date.
  • Counts. Say what a number counts, in the badge or in the text next to it: “3 new messages”.
  • Changes. A badge that changes is not announced. When the change matters, such as a new message, announce it another way, for example with a toast or a role="status" region of your own.

The badge takes no focus and has no keys of its own.

What every element shares is in Accessibility.