Badge

When to use

Reach for a badge when something needs a quick, glanceable nudge, such as an unread count on an inbox tab, a "new" dot on a menu item, or a notification number on an icon. It's meant to sit next to something else, not stand alone. See Alternatives below if what you're showing is a status or category someone should be able to read on its own.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/badge.js";

<eun-badge>5</eun-badge>

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/badge.js";
</script>

<eun-badge>5</eun-badge>

npm install @eunomia/elements

import "@eunomia/elements/badge.js";

function UnreadBadge() {
  return <eun-badge>5</eun-badge>;
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/badge.js";

export function UnreadBadge() {
  return <eun-badge>5</eun-badge>;
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/badge.js";
</script>

<template>
  <eun-badge>5</eun-badge>
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/badge.js";

@Component({
  selector: "app-unread-badge",
  template: `<eun-badge>5</eun-badge>`,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class UnreadBadgeComponent {}

Alternatives

Guidance

Live testing

Properties

Basic

An empty <eun-badge> renders as a plain dot, and any slotted content turns it into a pill.

<eun-badge></eun-badge>
<eun-badge>5</eun-badge>
<eun-badge>99</eun-badge>

Variants

Colors

<eun-badge color="primary">1</eun-badge>
<eun-badge color="secondary">2</eun-badge>
<eun-badge color="critical">3</eun-badge>
<eun-badge color="success">4</eun-badge>
<eun-badge color="warning">5</eun-badge>

Part of the shared vocabulary, alongside every other component that reuses it.

Sizes

<eun-badge size="s">1</eun-badge>
<eun-badge size="m">1</eun-badge>
<eun-badge size="l">1</eun-badge>

In context

In a tab

eun-tab reserves a dedicated badge slot for exactly this purpose. Dropping a <eun-badge> into it positions the badge the same way eun-tab's own built-in dot indicator (its boolean badge attribute) already does, without losing the ability to show a real count.

<eun-tab-group>
  <eun-tab slot="navigation" panel="inbox">
    Inbox
    <eun-badge slot="badge">5</eun-badge>
  </eun-tab>
  <eun-tab slot="navigation" panel="sent">Sent</eun-tab>
  <eun-tab-panel name="inbox">5 unread messages.</eun-tab-panel>
  <eun-tab-panel name="sent">No sent messages.</eun-tab-panel>
</eun-tab-group>

See Tabs for the rest of the eun-tab/eun-tab-group API.

Overlaying an icon

There's no dedicated "overlay" API. Position the badge with plain CSS against a position: relative wrapper, the same technique any icon library composition would use.

<span style="position: relative; display: inline-flex;">
  <eun-icon name="notifications" size="24"></eun-icon>
  <eun-badge label="3 unread notifications" class="badge-overlay">3</eun-badge>
</span>

.badge-overlay {
  position: absolute;
  top: -4px;
  right: -4px;
}

Server-side rendering

Before the badge upgrades, its content is plain inline text. Link badge-ssr.css in the page's <head> to draw the final badge from the first paint:

<link
  rel="stylesheet"
  href="node_modules/@eunomia/elements/dist/ssr/badge-ssr.css"
/>

A bundler that resolves package exports can reach it as @eunomia/elements/badge-ssr.css.

It covers every size and color, the empty dot, and the --badge-* properties.

Custom

Override the --badge-* CSS variables, listed in full in the API tab. The shape itself (always fully rounded) isn't one of them.

<eun-badge class="custom-badge">12</eun-badge>

.custom-badge {
  --badge-background: #7c3aed;
  --badge-color: #fff;
  --badge-size: 24px;
  --badge-font-size: 13px;
}

The custom properties that change colors, borders, shadows and corners, at a glance. The API tab lists every property of the component.

Decorative by default

With no label set, eun-badge is aria-hidden="true". It carries no ARIA role and contributes nothing to the accessibility tree. This matches the posture of eun-tag's own icon and eun-tab's pre-existing boolean dot indicator, both purely visual accents rather than independent pieces of content. This is the right default whenever the badge sits next to text that already states its meaning. Take a tab labeled "Inbox" next to a 5 badge. A screen reader announcing just "Inbox" isn't losing essential information that a sighted user has and a non-sighted one doesn't, as long as the surrounding UI (or the tab panel's own content) states the actual count somewhere perceivable.

Making it announced with label

Set label whenever the badge is the sole carrier of information, most commonly an icon-only trigger with no other visible or accessible text nearby (see the "Overlaying an icon" example). With label set, the badge switches to role="status" and aria-label="<label>", and drops aria-hidden. role="status" is a polite live region, appropriate for a count that can change without an explicit user action forcing a re-read, unlike role="alert", which interrupts.

Aria attributes

• aria-hidden="true": set whenever label is unset (the default)
• role="status" + aria-label="<label>": set instead whenever label is provided, kept in sync on every subsequent label change

Reference links

WAI-ARIA: status role
WAI-ARIA Authoring Practices: Read Me First (live regions)