MISCBETA

Badge

Compact counts, statuses and metadata with a standalone component, a hydration-safe arbitrary-anchor directive and native Button integration.

Logical positionsRTL readyHeadless ready

GET STARTED

Import

Import the canonical component and directive from the granular entry point.

import {
  NeuralBadge,
  NeuralBadgeDirective,
} from '@neural-ng/core/badge';

@Component({ imports: [NeuralBadge, NeuralBadgeDirective] })

Values and numeric caps

Strings and every finite number are valid. max only caps presentation; the uncapped number remains the accessible value.

New

99+

-2

Semantic severities

Every semantic role follows the active primary, surface and color-mode tokens.

Primary

Secondary

Neutral

Info

Success

Warning

Error

Sizes, dots and projected content

Three presets, optional square geometry, meaningful dots and rich projected content cover compact metadata without a second component.

Verified

Live counter

Signal values update directly. Use a polite live region only when the update deserves an announcement.

Arbitrary anchor directive

NeuralBadgeDirective creates the real Badge component on any suitable host after hydration.

Logical positions

Inline start/end participate in layout. Four corner positions overlay the anchor and mirror automatically in RTL.

startendtop-starttop-endbottom-startbottom-end

Button integration

When a Badge belongs to an action, use NeuralButton's shorter API. It delegates to the same directive contract.

Visibility and empty values

Zero is content. A directive value of null or undefined removes its generated host; badgeHidden is the explicit component visibility switch.

Notifications

Unstyled and typed class slots

Structural hooks remain while all NeuralNg visual ownership moves to consumer classes.

Composition boundaries

Standalone

Inline status, count or projected metadata.

Directive

Decoration for arbitrary non-void anchors.

Button API

The shortest contract for action-owned badges.

ACCESSIBILITY

Small visual, complete meaning

Badge never replaces the accessible name of the object it decorates.

Labels and caps

A capped 99+ Badge exposes the real numeric value through its generated aria-label. Set ariaLabel when the number needs context, and keep the anchor's own name complete.

Meaningful dots

A decorative dot needs no announcement. A dot that means online, unread or failed must receive ariaLabel; development mode warns when it is missing.

Live regions

ariaLive="off" is intentionally the default. Prefer polite for user-relevant background counts and reserve assertive for truly urgent changes.

Anchor semantics

The directive does not change role, focus or keyboard behavior. Use a real Button for actions. Wrap void or replaced elements such as img and input before applying the directive.

RTL and logical placement

start and end are logical, not physical. All corner offsets use logical inset properties and follow the document direction without a second API.

PUBLIC API

Badge contract

Canonical symbols are NeuralBadge and NeuralBadgeDirective. Legacy aliases remain deprecated for migration only.

NeuralBadge inputs

Input	Type	Default	Purpose
value	string \| number \| null \| undefined	null	Visible value; absence projects content.
max	number \| null	null	Finite non-negative numeric visual cap.
severity	NeuralBadgeSeverity	'neutral'	Semantic color treatment.
size	small \| medium \| large	'medium'	Preset dimensions and type scale.
rounded	boolean	true	Uses pill radius when enabled.
dot	boolean	false	Renders a visual dot without value text.
badgeHidden	boolean	false	Explicitly hides the component host.
ariaLabel	string \| null	null/capped value	Accessible label override.
ariaLive	off \| polite \| assertive	'off'	Live-region announcement mode.
unstyled	boolean	false	Removes NeuralNg visual classes.
badgeClass	string	''	Additive root class.
classes	NeuralBadgeClasses	{}	Typed additive class slots.

NeuralBadgeDirective inputs

Input	Type	Default	Purpose
neuralBadge	string \| number \| null \| undefined	null	Generated Badge value.
neuralBadgePosition	NeuralBadgePosition	'top-end'	Inline or logical-corner placement.
neuralBadgeSeverity	NeuralBadgeSeverity	'neutral'	Generated Badge severity.
neuralBadgeSize	NeuralBadgeSize	'small'	Generated Badge size.
neuralBadgeMax	number \| null	null	Numeric visual cap.
neuralBadgeAriaLabel	string \| null	null	Accessible Badge label.
neuralBadgeAriaLive	NeuralBadgeAriaLive	'off'	Live-region behavior.
neuralBadgeClass	string	''	Class for generated Badge root.
neuralBadgeHostClass	string	''	Class for generated host element.
neuralBadgeRounded	boolean	true	Rounded generated Badge.
neuralBadgeDot	boolean	false	Dot generated Badge.
neuralBadgeHidden	boolean	false	Explicitly removes generated host.
neuralBadgeUnstyled	boolean	false	Removes generated visual classes.

Typed class slots

rootvaluecontent

Public types

NeuralBadgeSeverity

NeuralBadgeSize

small | medium | large

NeuralBadgeAriaLive

off | polite | assertive

NeuralBadgePosition

DESIGN TOKENS

Badge tokens

Neutral responds to runtime primary, surface and mode. Glass and Futuristic override the same contract without changing markup.

Base tokens

--neural-badge-min-width

Component minimum inline size.

--neural-badge-height

Component block size.

--neural-badge-padding

Component internal spacing.

--neural-badge-color

Component foreground color.

--neural-badge-background

Component background surface.

--neural-badge-border

Component border shorthand.

--neural-badge-radius

Component corner radius.

--neural-badge-rounded-radius

Rounded corner radius.

--neural-badge-shadow

Component box shadow.

--neural-badge-font-family

Component font family.

--neural-badge-font-size

Component font size.

--neural-badge-font-weight

Component font weight.

--neural-badge-line-height

Component line height.

--neural-badge-small-min-width

Small minimum inline size.

--neural-badge-small-height

Small block size.

--neural-badge-small-padding

Small internal spacing.

--neural-badge-small-font-size

Small font size.

--neural-badge-large-min-width

Large minimum inline size.

--neural-badge-large-height

Large block size.

--neural-badge-large-padding

Large internal spacing.

--neural-badge-large-font-size

Large font size.

--neural-badge-dot-size

Dot width and height.

--neural-badge-dot-small-size

Dot small width and height.

--neural-badge-dot-large-size

Dot large width and height.

--neural-badge-content-gap

Spacing between content items.

Severity tokens

--neural-badge-primary-color

Primary severity foreground color.

--neural-badge-primary-background

Primary severity background surface.

--neural-badge-primary-border-color

Primary severity border color.

--neural-badge-secondary-color

Secondary severity foreground color.

--neural-badge-secondary-background

Secondary severity background surface.

--neural-badge-secondary-border-color

Secondary severity border color.

--neural-badge-neutral-color

Neutral severity foreground color.

--neural-badge-neutral-background

Neutral severity background surface.

--neural-badge-neutral-border-color

Neutral severity border color.

--neural-badge-info-color

Info severity foreground color.

--neural-badge-info-background

Info severity background surface.

--neural-badge-info-border-color

Info severity border color.

--neural-badge-success-color

Success severity foreground color.

--neural-badge-success-background

Success severity background surface.

--neural-badge-success-border-color

Success severity border color.

--neural-badge-warning-color

Warning severity foreground color.

--neural-badge-warning-background

Warning severity background surface.

--neural-badge-warning-border-color

Warning severity border color.

--neural-badge-error-color

Error severity foreground color.

--neural-badge-error-background

Error severity background surface.

--neural-badge-error-border-color

Error severity border color.

Anchor tokens

--neural-badge-anchor-offset

Anchor positional offset.

--neural-badge-anchor-z-index

Anchor stacking order.