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
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> );}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/badge';
@Component({ selector: 'app-badge-basic', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <p>Invoice 1042 <gui-badge variant="success">Paid</gui-badge></p> `,})export class BadgeBasicComponent {}<script setup lang="ts">import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';</script>
<template> <p>Invoice 1042 <gui-badge variant="success">Paid</gui-badge></p></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';
@customElement('badge-basic')export class BadgeBasic extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <p>Invoice 1042 <gui-badge variant="success">Paid</gui-badge></p> `; }}<p>Invoice 1042 <gui-badge variant="success">Paid</gui-badge></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.
import { GuiBadge } from '@golemui/gui-components/react';import '@golemui/gui-components/index.css';
export function BadgeExample() { return ( <GuiBadge variant="success" > Paid </GuiBadge> );}Add CUSTOM_ELEMENTS_SCHEMA to the component that uses the tags, and the stylesheet to styles in angular.json.
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/badge';
@Component({ selector: 'app-badge-example', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <gui-badge variant="success" > Paid </gui-badge> `,})export class BadgeExampleComponent {}"styles": ["node_modules/@golemui/gui-components/lib/styles/index.css"]Tell Vue's compiler that gui-* tags are custom elements, and add the typings once for typed props and @gui-* handlers.
<script setup lang="ts">import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';</script>
<template> <gui-badge variant="success" > Paid </gui-badge></template>vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('gui-') } },});import type {} from '@golemui/gui-components/vue';The page's stylesheet styles the gui-* elements, so it only reaches them outside a shadow root. Render the host component into the light DOM too, as below, or load the stylesheet into its shadow root.
import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';
@customElement('badge-example')export class BadgeExample extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <gui-badge variant="success" > Paid </gui-badge> `; }}With any bundler, such as Vite. Import the element once, anywhere, and use the tag in your markup.
<gui-badge variant="success"> Paid</gui-badge>
<script type="module" src="./main.js"></script>import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';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. |
Examples
Section titled “Examples”Variants
Section titled “Variants”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.
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> );}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/badge';
@Component({ selector: 'app-badge-variants', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <p> <gui-badge>Draft</gui-badge> <gui-badge variant="info">New</gui-badge> <gui-badge variant="success">Paid</gui-badge> <gui-badge variant="warning">Due soon</gui-badge> <gui-badge variant="error">Overdue</gui-badge> </p> `,})export class BadgeVariantsComponent {}<script setup lang="ts">import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';</script>
<template> <p> <gui-badge>Draft</gui-badge> <gui-badge variant="info">New</gui-badge> <gui-badge variant="success">Paid</gui-badge> <gui-badge variant="warning">Due soon</gui-badge> <gui-badge variant="error">Overdue</gui-badge> </p></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';
@customElement('badge-variants')export class BadgeVariants extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <p> <gui-badge>Draft</gui-badge> <gui-badge variant="info">New</gui-badge> <gui-badge variant="success">Paid</gui-badge> <gui-badge variant="warning">Due soon</gui-badge> <gui-badge variant="error">Overdue</gui-badge> </p> `; }}<p> <gui-badge>Draft</gui-badge> <gui-badge variant="info">New</gui-badge> <gui-badge variant="success">Paid</gui-badge> <gui-badge variant="warning">Due soon</gui-badge> <gui-badge variant="error">Overdue</gui-badge></p>In text
Section titled “In text”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
Inbox
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> </> );}import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';import '@golemui/gui-components/badge';
@Component({ selector: 'app-badge-in-text', schemas: [CUSTOM_ELEMENTS_SCHEMA], template: ` <p>Billing <gui-badge variant="warning">Action needed</gui-badge></p> <p>Inbox <gui-badge variant="info">3 new messages</gui-badge></p> `,})export class BadgeInTextComponent {}<script setup lang="ts">import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';</script>
<template> <p>Billing <gui-badge variant="warning">Action needed</gui-badge></p> <p>Inbox <gui-badge variant="info">3 new messages</gui-badge></p></template>import { LitElement, html } from 'lit';import { customElement } from 'lit/decorators.js';import '@golemui/gui-components/badge';import '@golemui/gui-components/index.css';
@customElement('badge-in-text')export class BadgeInText extends LitElement { protected override createRenderRoot() { return this; }
override render() { return html` <p>Billing <gui-badge variant="warning">Action needed</gui-badge></p> <p>Inbox <gui-badge variant="info">3 new messages</gui-badge></p> `; }}<p>Billing <gui-badge variant="warning">Action needed</gui-badge></p><p>Inbox <gui-badge variant="info">3 new messages</gui-badge></p>Styling
Section titled “Styling”Anatomy
Section titled “Anatomy”<gui-badge> renders nothing of its own. It is your text, styled:
<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:
| Selector | Part |
|---|---|
gui-badge | The 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.
Tokens
Section titled “Tokens”The badge reads these design tokens. Set them on :root to change every badge, or on any element
to change the badges inside it:
| Token | What it styles |
|---|---|
--gui-badge-height | The smallest height of the badge. 1.25rem by default. |
--gui-badge-radius | The corner radius. var(--gui-radius-full) by default: a pill. |
--gui-badge-font-size | The text size. var(--gui-font-xs) by default. |
--gui-space-2 | The space at the start and end of the badge. |
--gui-bg-surface-hover, --gui-border-default, --gui-text-default | The background, border and text of the neutral badge. |
--gui-intent-info-bg, --gui-intent-info, --gui-intent-info-text | The background, border and text of info. |
--gui-intent-success-bg, --gui-intent-success, --gui-intent-success-text | The background, border and text of success. |
--gui-intent-warning-bg, --gui-intent-warning, --gui-intent-warning-text | The background, border and text of warning. |
--gui-intent-error-bg, --gui-intent-error, --gui-intent-error-text | The background, border and text of error. |
The intent tokens are listed in Tokens.
/* 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.
Accessibility
Section titled “Accessibility”- 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.