OverlayBadge
A count on a corner.
About
Pins a small sui-badge to a corner of the child in its slot: the unread count on a bell, a presence dot on an avatar. The badge is always the sm size and wears a 2px surface ring so it reads over the child. Give the child a label that includes the number, because the badge itself has none.
Usage
<sui-overlay-badge value="3">
<sui-icon-button icon="fa-regular fa-bell" variant="outline" aria-label="Notifications, 3 unread"></sui-icon-button>
</sui-overlay-badge>
<script type="module">
import { defineCustomElements } from "@shineui/core/loader";
import "@shineui/core/shineui.css";
defineCustomElements();
</script>
import { SuiOverlayBadge } from "@shineui/react";
import "@shineui/core/shineui.css";
export function Example() {
return (
<SuiOverlayBadge value="3">
<sui-icon-button icon="fa-regular fa-bell" variant="outline" aria-label="Notifications, 3 unread"></sui-icon-button>
</SuiOverlayBadge>
);
}
<script setup>
import { SuiOverlayBadge } from "@shineui/vue";
import "@shineui/core/shineui.css";
</script>
<template>
<SuiOverlayBadge value="3"><sui-icon-button icon="fa-regular fa-bell" variant="outline" aria-label="Notifications, 3 unread"></sui-icon-button></SuiOverlayBadge>
</template>
import { Component } from "@angular/core";
import { SuiOverlayBadge } from "@shineui/angular";
@Component({
standalone: true,
imports: [SuiOverlayBadge],
template: `<sui-overlay-badge value="3"><sui-icon-button icon="fa-regular fa-bell" variant="outline" aria-label="Notifications, 3 unread"></sui-icon-button></sui-overlay-badge>`,
})
export class Example { }
Basic
The badge itself carries no role or label, so the count reaches assistive tech only through the control underneath. Give that control an aria-label that already includes the number, as the bell does here.
<sui-overlay-badge value="3">
<sui-icon-button icon="fa-regular fa-bell" variant="outline" aria-label="Notifications, 3 unread"></sui-icon-button>
</sui-overlay-badge>
Positions
Four corners. The badge wears a 2px surface ring so it stays readable over a busy child.
<div style="display:flex;flex-wrap:wrap;gap:22px;align-items:center">
<sui-overlay-badge value="3"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-regular fa-bell" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
<sui-overlay-badge value="3" position="top-left"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-regular fa-envelope" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
<sui-overlay-badge value="3" position="bottom-right"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-regular fa-file-lines" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
<sui-overlay-badge value="3" position="bottom-left"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-regular fa-comment" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
</div>
Severities and the dot
The overlay defaults to accent, unlike a bare badge, which defaults to brand. Use dot for presence, where there is no number to show.
<div style="display:flex;flex-wrap:wrap;gap:22px;align-items:center">
<sui-overlay-badge value="9"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-regular fa-bell" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
<sui-overlay-badge value="9" severity="brand"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-regular fa-bell" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
<sui-overlay-badge value="9" severity="soft"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-regular fa-bell" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
<sui-overlay-badge dot severity="critical"><span style="width:36px;height:36px;border-radius:8px;border:1px solid var(--border-strong);display:inline-flex;align-items:center;justify-content:center;color:var(--ink-muted)"><i class="fa-solid fa-triangle-exclamation" style="font-size:14px" aria-hidden="true"></i></span></sui-overlay-badge>
<sui-overlay-badge dot severity="accent">
<sui-avatar name="Dana Whitfield" size="lg"></sui-avatar>
</sui-overlay-badge>
<span style="font:460 12px/1.6 var(--font-sans);color:var(--ink-faint)">The badge is always the sm size, whatever the child.</span>
</div>
API
<sui-overlay-badge>
Properties
| Property | Attribute | Type | Default | Description |
|---|---|---|---|---|
dot | dot | boolean | false | Presence dot instead of a count. |
position | position | SuiOverlayBadgePosition"bottom-left" | "bottom-right" | "top-left" | "top-right" | 'top-right' | Which corner of the child the badge sits on. Reflected. |
severity | severity | SuiBadgeSeverity"accent" | "attention" | "brand" | "critical" | "info" | "neutral" | "positive" | "soft" | 'accent' | Badge color role from the status system. Defaults to accent, unlike a bare badge. Reflected. |
value | value | number | string | undefined | Count or short text shown in the badge. Ignored in dot mode. |
Slots
| Slot | Description |
|---|---|
(default) | The element the badge is anchored to (an icon button, an avatar). Wrap exactly one child. |
Types
SuiBadgeSeverity typeThe shared status ladder plus the three emphasis roles a count badge also needs. | |||
|---|---|---|---|
| No members. |
SuiOverlayBadgePosition type | |||
|---|---|---|---|
| No members. |
SuiSeverity type | |||
|---|---|---|---|
| No members. |
Theming
Every design token this element can render with, read from its own stylesheets and the ones it imports. Set a token on :root or on any ancestor and every use below follows it. The values shown are the ones in the theme you are viewing. The list is read per stylesheet, so an element that imports a shared drawing module lists that module's tokens too, whether or not it paints with all of them.
Color1
Typography1
Every name above is listed with its value and its role in Foundations.