gogBadge

Badge

A count or status dot pinned to the corner of another element. A directive, not a component — it decorates a button, an icon or an avatar without wrapping it, so the host's own layout is untouched.

Overview

Import the directive and put it on the element to decorate.

import { GogBadgeDirective } from '@guildofgleks/ui';

@Component({
  // ...
  imports: [GogBadgeDirective],
})

Basic usage:

<gog-button gogBadge="12" badgeAriaLabel="12 unread messages">Inbox</gog-button>

It never renders "0"

A badge reading 0 is the defining bug of this component class, so it is not reachable: 0, null and '' render nothing at all. That means a call site can bind a count straight from state without guarding it behind an @if.

count = 3

<!-- 0 renders nothing at all — a badge reading "0" is not reachable. -->
<gog-button [gogBadge]="0">Zero</gog-button>
<gog-button [gogBadge]="5">Five</gog-button>

<!-- 128 with the default badgeMax of 99. -->
<gog-button [gogBadge]="128">Capped</gog-button>

<!-- badgeHidden takes it out of the DOM without removing the directive. -->
<gog-button [gogBadge]="5" [badgeHidden]="true">Hidden</gog-button>

Examples

Variants

The library's four semantic colors. danger is the default, since an unread count is the common case.

<gog-button gogBadge="7" badgeVariant="success">Passed</gog-button>
<gog-button gogBadge="7" badgeVariant="danger">Failed</gog-button>
<gog-button gogBadge="7" badgeVariant="warning">Flaky</gog-button>
<gog-button gogBadge="7" badgeVariant="info">Skipped</gog-button>

Positions

Named by block/inline edge rather than left/right, so the badge follows the writing direction in an RTL layout.

<gog-button gogBadge="4" badgePosition="top-end">top-end</gog-button>
<gog-button gogBadge="4" badgePosition="top-start">top-start</gog-button>
<gog-button gogBadge="4" badgePosition="bottom-end">bottom-end</gog-button>
<gog-button gogBadge="4" badgePosition="bottom-start">bottom-start</gog-button>

Dot

badgeDot drops the text and leaves a mark — "something changed here", with no count to give. A dot shows even with no value bound.

<!-- A dot says "something changed here" with no count to give. -->
<gog-icon name="info" gogBadge badgeDot badgeAriaLabel="Unread updates" />

<gog-button gogBadge badgeDot badgeVariant="success">Synced</gog-button>

Caps and hiding

Counts above badgeMax (99 by default) render as N+. Non-numeric content passes through untouched, so "NEW" works as a label. badgeHidden keeps the badge out of the DOM without removing the directive.

Accessibility

Left alone, the badge text is announced inline with the host's own label — "Inbox 12". Set badgeAriaLabel and the visible badge becomes aria-hidden while your wording is announced in its place, so the host reads as "Inbox, 12 unread messages" instead. A dot has no text of its own, so it needs badgeAriaLabel to be announced at all.

The badge node is created in the browser only. That is deliberate: a node the server renders but the client's hydration walk knows nothing about is an NG0500 mismatch, so it costs one frame after hydration and buys a directive that is safe in an SSR app.

API Reference

Inputs

Name	Type	Default	Description
`gogBadge`	`string \| number \| null`	`null`	The badge content. Numbers above badgeMax render as "N+". Non-numeric content ("NEW", "beta") passes through untouched.
`badgePosition`	`'top-end' \| 'top-start' \| 'bottom-end' \| 'bottom-start'`	`'top-end'`	Which corner of the host the badge sits on. Named by block/inline edge rather than left/right, so it follows the writing direction in an RTL layout.
`badgeVariant`	`'success' \| 'danger' \| 'warning' \| 'info'`	`'danger'`	Semantic color — the same four names gog-tag takes.
`badgeDot`	`boolean`	`false`	Renders a bare dot with no text: "something changed here", with no count to give. A dot shows even when there is no value.
`badgeMax`	`number`	`99`	Counts above this render as "N+" rather than growing without limit.
`badgeHidden`	`boolean`	`false`	Keeps the badge out of the DOM without removing the directive.
`badgeAriaLabel`	`string`	`''`	What assistive tech hears instead of the bare number. Set it and the visible badge becomes aria-hidden while this wording is announced in its place.

Styling Tokens

Every CSS custom property the badge paints with. Override any of them — on a single instance, a subtree, or a theme — to restyle it. See the Theming guide for the full token-layering model, or the Theme Generator to tweak these live.

Token	Description
`--gog-badge-success-bg / -danger-bg / -warning-bg / -info-bg (+ matching -color)`	Fill and text color per semantic variant.
`--gog-badge-size / -dot-size / -padding-inline`	Badge height, the bare-dot diameter, and horizontal padding around a count.
`--gog-badge-radius / -border-color / -border-width / -border-style`	Corner radius and the ring separating the badge from its host.
`--gog-badge-font-family / -font-size / -font-weight / -line-height`	Count typography.
`--gog-badge-offset / -z`	How far the badge overhangs its host corner, and its stacking order.