GUILD OF GLEKS UIv21.19.0

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.

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

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

Basic usage:

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

Examples

Content and variants

Five kinds of content in the four semantic colours, which are the names gog-tag takes. danger is the default, the colour of a count someone should look at. A number over badgeMax (99) prints as 99+; a word is left alone, since capping only means something for a count. badgeDot drops the text for "something changed here", with no number to give.

gogBadge="3"
gogBadge="42"
gogBadge="150"
gogBadge="NEW"
badgeDot
@for (content of contents; track content.label) {
  <div>
    <span>{{ content.label }}</span>
    @for (variant of variants; track variant) {
      <gog-button
        variant="outline"
        [gogBadge]="content.value"
        [badgeDot]="content.dot"
        [badgeVariant]="variant"
      >
        {{ variant }}
      </gog-button>
    }
  </div>
}

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, and a call site can bind a count straight from state without an @if. Step the count down to zero. badgeHidden is the other way to take the badge away — the count underneath is kept, so it comes back as it was. Neither changes the host's size, because the badge was never part of its layout.

count: 3

<!-- Bind the count straight from state: 0, null and '' render no badge at all. -->
<gog-button [gogBadge]="count()" [badgeHidden]="hidden()" badgeAriaLabel="{{ count() }} unread">
  Notifications
</gog-button>
<gog-button variant="outline" (gogClick)="remove()">−1</gog-button>
<gog-button variant="outline" (gogClick)="add()">+1</gog-button>
<gog-button variant="outline" (gogClick)="count.set(150)">Set 150</gog-button>
<gog-button variant="outline" (gogClick)="hidden.set(!hidden())">
  badgeHidden: {{ hidden() }}
</gog-button>

<p>count: {{ count() }}</p>

Positions

The four corners, as logical positions: end is the right-hand corner here and the left-hand one in a right-to-left page. The badge overhangs the corner by --gog-badge-offset, so leave that much room around a badged element in a tight row.

@for (position of positions; track position) {
  <gog-button variant="outline" gogBadge="9" [badgePosition]="position">
    {{ position }}
  </gog-button>
}

Hosts

A directive, so it decorates what is already there rather than wrapping it: a gog-button, a native button, a link styled with gogButton, or any element — the host only gains position: relative to hold the badge. An inline element has to be made a box (inline-flex on the span) so the corner is its corner. A round gog-avatar moves the anchor onto its circle 21.17.0, so the dot sits on the edge rather than in the empty corner of the avatar's box — it sets --gog-badge-host-inset and --gog-badge-dot-offset on itself, and any round host of your own can do the same.

a[gogButton]span
<gog-button gogBadge="12">gog-button</gog-button>
<button type="button" style="padding: 4px 12px; font: inherit" gogBadge="4">native button</button>
<a gogButton href="#overview" gogBadge="NEW" badgeVariant="success">a[gogButton]</a>
<!-- An inline element made a box, so the badge's corner is its corner. -->
<span style="display: inline-flex; padding: 8px" gogBadge="2">span</span>
<!-- A round gog-avatar anchors the badge on its circle, not in the empty corner of its box. -->
<gog-avatar name="Guild of Gleks" initials="GG" gogBadge badgeDot badgeVariant="success" />

Dot

A dot shows even with no value bound. It has no text of its own, so give it badgeAriaLabel — and put it on the control it belongs to, not on that control's icon: a gog-icon is aria-hidden, so a badge inside one is never announced.

<!-- On the button, not on its icon: a gog-icon is aria-hidden, and so is a badge inside it. -->
<gog-button
  variant="ghost"
  ariaLabel="Notifications"
  gogBadge
  badgeDot
  badgeAriaLabel="Unread updates"
>
  <gog-icon name="info" />
</gog-button>
<gog-button gogBadge badgeDot badgeVariant="success">Synced</gog-button>

Caps

Counts above badgeMax (99 by default) render as N+, so a badge never grows without limit. Non-numeric content passes through untouched, so a word works as a label.

<gog-button variant="outline" [gogBadge]="128">default badgeMax</gog-button>
<gog-button variant="outline" [gogBadge]="128" [badgeMax]="999">badgeMax=999</gog-button>
<gog-button variant="outline" [gogBadge]="1280" [badgeMax]="999">badgeMax=999</gog-button>
<gog-button variant="outline" gogBadge="beta" badgeVariant="info">a word</gog-button>

Accessibility

badgeAriaLabel replaces the visible badge text for assistive tech — the visible badge becomes aria-hidden and your wording is read instead. A dot has no text of its own, so it needs badgeAriaLabel to be announced at all. What the wording becomes depends on the host:

  • A focusable host — <button gogBadge>, a[gogButton] — gets it as part of its name: "Inbox 12 unread".
  • A host whose focusable element is inside it, like gog-button, gets it as a description of that element, through aria-describedby: "Inbox, button, 12 unread" 21.15.0. Before 21.15.0 the badge landed beside the inner button rather than on it, and Tab said only "Inbox, button".
  • A host whose children are not read — role="img", which a named gog-avatar is — gets it as its own description the same way: "Ada Lovelace, image, 3" 21.17.0. Before 21.17.0 the count was drawn but never heard.
  • A host with nothing focusable gets plain text after its own — and inside a decorative gog-icon, which is aria-hidden, nothing at all. Put the badge on the control the count belongs to.
  • Wording — without badgeAriaLabel a screen reader hears the bare number, "Inbox 12", which is often enough. Give the wording when the number alone is ambiguous — "12 unread", "3 failed checks" — and keep it in step with the count, as the "0" example does.
  • Keyboard — none of its own. The badge is never a tab stop; the host keeps its own keyboard behaviour unchanged.

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

NameTypeDefaultDescription
gogBadgestring | number | nullnullThe 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.
badgeDotbooleanfalseRenders a bare dot with no text: "something changed here", with no count to give. A dot shows even when there is no value.
badgeMaxnumber99Counts above this render as "N+" rather than growing without limit.
badgeHiddenbooleanfalseKeeps the badge out of the DOM without removing the directive.
badgeAriaLabelstring''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.

Global Configuration

This component has no GOG_CONFIG entries of its own — every default is set per instance. See Global Configuration for what does apply app-wide.

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.

TokenDescription
--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-inlineBadge height, the bare-dot diameter, and horizontal padding around a count.
--gog-badge-radius / -border-color / -border-width / -border-styleCorner radius and the ring separating the badge from its host.
--gog-badge-font-family / -font-size / -font-weight / -line-heightCount typography.
--gog-badge-offset / -zHow far the badge overhangs its host corner, and its stacking order.
--gog-badge-host-inset / -dot-offsetWhere the badge anchors, in from the host’s box corner (0 for a box), and the dot’s own overhang (the shared offset by default). A round gog-avatar sets both on itself, so a count sits on the edge of its circle and a dot is centred on it.