Badge handbook

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Use compact numbers, text, or dots to show unread counts and status alongside buttons, avatars, and navigation items.

When to use it

Use Badge for short status or count cues. Use Button when a click should perform an action; choose Chip or Tag for actionable labels in an input according to the needed interaction.

• children takes precedence over count; an explicit dot shows only a dot, without content.

• Counts display up to 99 by default, and zero is hidden. Change this with max and showZero. Use as="badge" for a badge attached to Avatar or Icon.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { Avatar, Badge } from '@snowui-design-system/components';	import { AvatarAbstract03 } from '@snowui-design-system/resource-svelte';</script> <div style="display: flex; align-items: center; flex-wrap: wrap; gap: var(--gap-4) var(--gap-3);">	<Avatar fallbackColor="orange" aria-label="Release notifications" size={48}><Badge as="badge" count={5} /></Avatar>	<Avatar fallbackColor="cyan" aria-label="Documentation inbox" size={48} badgePosition="bottom"><Badge as="badge" count={120} max={99} color="Orange" /></Avatar>	<Avatar src={AvatarAbstract03} aria-label="New components" size={48}><Badge as="badge" count="New" color="Red" /></Avatar>	<Avatar fallbackColor="red" aria-label="Maintainer online" size={48} badgePosition="bottom"><Badge as="badge" dot color="Green" /></Avatar></div>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Keywords

Layout model

Main layout model: inline shell. See specs/maintainers/LayoutProtocol.md §12.4.

The Badge root is an inline-level positioning shell whose content sizes to fit:

• The inline-flex root handles host positioning, size measurement, and Frame translation. Its default flex-shrink: 0 preserves text and padding in narrow horizontal containers.

• The inner .snowui-badge-surface owns background, padding, radius, minimum width, font size, and line height. It also animates scale, opacity, and blur as one visual Badge.

• The private snowui-morph-container uses grid stacking to keep layout stable as numbers change. Its content is anchored at the container’s 50% point and offset by 50% of its own size, so text overflows symmetrically when a fixed size is narrower than the text. Text and numbers remain geometrically centered without relying on grid safe-overflow fallback. This private structure does not change the main layout model.

• In dot mode, the inline shell becomes a fixed-size dot with zero padding.

• as="badge" assigns an attachment role for Icon/Avatar; it does not change Badge’s internal layout.

Layout variable chain:

variant="border" uses the same token values as Kbd’s default border style while retaining Badge’s status-label semantics and <span>/Frame shell:

border applies only to text content mode; dot retains its dot appearance. As a descendant of Button, SidebarItem, or a similar host, border sizes to its text instead of inheriting a fixed square size. Its morph text layer inherits var(--leading-12) instead of the compact line-height: 1 used by filled Badge, matching Kbd’s default border height.

color follows SnowUI’s public semantic color protocol and is case-sensitive:

<Badge count={1} color="Blue" /><Badge count={2} color="Red" /><Badge dot color="Green" /><Badge count="New" variant="border" />

Role-oriented combination

 <Icon size={24}>    {#snippet badge()}        <Badge as="badge" count={5} />    {/snippet}    <Bell /></Icon>  <Badge count={99} max={99} /><Badge dot />

Intelligent behavior

1. Automatic hiding: Count mode appears by default only for values of at least 1. At 0 with showZero=false, it hides while retaining the last visible value during exit (for example, 1 exits without displaying 0).

2. Overflow formatting: Values above max display as max+.

3. Automatic content: When there is no count, try reading the parent element’s text.

4. Role-aware size inheritance:

   • Standalone: Read the parent Frame size context (for example, a list item) for adaptive scaling.

   • Attached badge (as="badge"): Ignore the parent Group size context; preserve badge proportions and let Avatar/Icon position it.

Default motion

Badge show and hide animations run in two parallel layers, following the transitions.dev notification badge structure:

• Frame currentState="Appear/Disappear" and whileAppear / whileDisappear animate the positioning shell: it slides from the lower left on entry and has no reverse translation on exit.

• The inner .snowui-badge-surface animates the complete visual Badge with scale, opacity, and blur. On entry it springs from scale(0), opacity: 0, and blur(2px); on exit the whole Badge, including its background, padding, and number, shrinks to zero around its center.

• The private .snowui-morph-container handles grid stacking and content centering only; it does not animate entry or exit.

When hidden, Badge keeps its DOM node for 180ms before removal. Exit has no reverse translation: the entire Badge shrinks around its center, fades, and blurs. whileAppear / whileDisappear={true} uses the full default Badge Frame motion. An explicit object specifies the complete visual channels to animate while inheriting Badge’s default timing; false disables the corresponding Frame motion. prefers-reduced-motion: reduce disables slide, pop, and blur transitions.

Private motion variables: