ng-hub-ui-badges

Español | English

Semantic Angular badges for statuses, counters and removable filter tags, with CSS variables and public SCSS mixins for custom colour families.

Documentation and Live Examples

This package is part of Hub UI, a collection of Angular component libraries for standalone apps.

• Docs: https://hubui.dev/badges/overview/
• Live examples: https://hubui.dev/badges/examples/
• Hub UI: https://hubui.dev/

Library Family ng-hub-ui

This library is part of the Hub UI ecosystem:

• ng-hub-ui-accordion (deprecated — use ng-hub-ui-panels)
• ng-hub-ui-action-sheet
• ng-hub-ui-avatar
• ng-hub-ui-badges ← You are here
• ng-hub-ui-board
• ng-hub-ui-breadcrumbs
• ng-hub-ui-buttons
• ng-hub-ui-calendar
• ng-hub-ui-dropdown
• ng-hub-ui-ds
• ng-hub-ui-forms
• ng-hub-ui-history
• ng-hub-ui-milestones
• ng-hub-ui-modal
• ng-hub-ui-nav
• ng-hub-ui-paginable
• ng-hub-ui-panels
• ng-hub-ui-portal
• ng-hub-ui-skeleton
• ng-hub-ui-sortable
• ng-hub-ui-stepper
• ng-hub-ui-toast
• ng-hub-ui-utils

Features

• HubBadgeComponent for labels, counters, status pills and removable tags.
• Six visual treatments: solid, soft, outline, ghost, subtle, surface.
• Six built-in semantic colours plus open custom semantic names.
• Size scale xs–lg and shapes pill, rounded, square.
• Optional status dot and accessible dismiss action; icons are projected as content.
• Public SCSS mixins at ng-hub-ui-badges/styles for custom semantic colour registration.

Installation

npm install ng-hub-ui-badges

Optional shared tokens:

npm install ng-hub-ui-ds

@import 'ng-hub-ui-ds/styles/tokens/hub-tokens.css';

Quick Start

import { Component } from '@angular/core';
import { HubBadgeComponent } from 'ng-hub-ui-badges';

@Component({
	standalone: true,
	imports: [HubBadgeComponent],
	template: `
		<div class="d-flex flex-wrap gap-2 align-items-center">
			<hub-badge color="success" [dot]="true">Online</hub-badge>
			<hub-badge variant="soft" color="danger" [removable]="true" removeLabel="Remove urgent filter">
				Urgent
			</hub-badge>
		</div>
	`
})
export class ExampleComponent {}

API

HubBadgeComponent

| Input | Type | Default | |---|---|---| | variant | HubBadgeVariant | 'solid' | | color | HubBadgeColor | 'primary' | | size | HubBadgeSize | 'md' | | shape | HubBadgeShape | 'pill' | | dot | boolean | false | | removable | boolean | false | | removeLabel | string | 'Remove badge' | | disabled | boolean | false | | tooltip | string | '' | | interactive | boolean | false | | active | boolean | false | | dotOverlay | boolean | false | | dotPlacement | HubBadgeOverlayPlacement | 'top-end' |

Outputs: removed, selected (emitted on click / Enter / Space while interactive).

Set interactive to turn a badge into a role="button" toggle; pair it with active to reflect the pressed state (--hub-badge-active-bg). dotOverlay pins the status dot to a corner (dotPlacement, offset via --hub-badge-overlay-offset) instead of the inline leading dot.

Long content is truncated with an ellipsis (bounded by --hub-badge-max-width). The full text is exposed as a tooltip: the explicit tooltip input always wins, otherwise the badge's own content is shown only while it overflows.

Icons are not an input — project them as content next to the label. The internal layout (--hub-badge-gap, --hub-badge-direction, --hub-badge-align) keeps them aligned:

<hub-badge color="danger"><i class="fa-solid fa-bell"></i> 5 alerts</hub-badge>

Arrange badges with the standard flex utilities — <div class="d-flex flex-wrap gap-2"> — rather than a dedicated component.

HubChipComponent

Interactive, togglable filter chip. Reuses the badge accent contract for its colours.

| Input | Type | Default | |---|---|---| | selected | boolean (two-way model) | false | | value | unknown | — | | color | HubBadgeColor | 'primary' | | disabled | boolean | false | | removable | boolean | false | | removeLabel | string | 'Remove chip' |

Outputs: selectedChange, removed, chipClick.

Project a leading icon or avatar through the [hubChipLeading] slot; the label is the default content. The chip is a role="button" toggle with aria-pressed and Space/Enter.

<hub-chip [(selected)]="onlyFailed" value="failed" color="danger">
	<i hubChipLeading class="fa-solid fa-triangle-exclamation"></i> Failed
</hub-chip>

HubChipSetComponent

Groups chips into a single- or multi-select set.

| Input | Type | Default | |---|---|---| | selectionMode | 'single' \| 'multiple' | 'single' | | value | unknown (two-way model) | — |

In single mode value holds the selected chip's value; in multiple mode it holds the array of selected values. Selecting a chip in single mode deselects its siblings.

<hub-chip-set [(value)]="status" selectionMode="single">
	<hub-chip value="open">Open</hub-chip>
	<hub-chip value="done">Done</hub-chip>
</hub-chip-set>

Tooltip synergy (optional, agnostic)

By default the overflow tooltip uses the native browser title attribute — zero dependencies. To upgrade every badge to the richer, themeable hub-ui tooltip, provide an adapter once (e.g. the one shipped by ng-hub-ui-utils):

import { provideHubBadgeTooltip } from 'ng-hub-ui-badges';
import { hubTooltipAdapter } from 'ng-hub-ui-utils';

export const appConfig: ApplicationConfig = {
  providers: [provideHubBadgeTooltip(hubTooltipAdapter)]
};

Remove the provider and badges fall back to the native tooltip. See the ecosystem-wide Synergies & agnosticism section for the full pattern.

Custom semantic colours

Every built-in colour — and any custom one — derives from a single semantic accent. There are three ways to register a custom colour, from simplest to most explicit.

1. Accent token only (no SCSS)

Set --hub-sys-color-<name> in any scope. The badge derives the soft, outline, subtle, … role colours from it automatically, across every variant:

:root {
	--hub-sys-color-brand: #7c3aed;
}

<hub-badge color="brand">Brand</hub-badge>
<hub-badge variant="soft" color="brand">Brand soft</hub-badge>

2. hub-badge-color-rules — full design-system family

When you already publish the complete --hub-sys-color-<name>-* token family, this helper pins every role to it. Run it inside a selector that targets .hub-badge:

@use 'ng-hub-ui-badges/styles' as hub;

:root {
	--hub-sys-color-brand: #7c3aed;
	--hub-sys-color-brand-subtle: #ede9fe;
	--hub-sys-color-brand-emphasis: #5b21b6;
	--hub-sys-color-brand-border-subtle: #c4b5fd;
}

.hub-badge {
	@include hub.hub-badge-color-rules('brand');
}

3. hub-badge-variant-rules — explicit values

To register a variant while pinning one or more final role slots to a designed value, pass the optional overrides. Anything you omit keeps the automatic runtime derivation, so this stays backward compatible with the accent-only form:

@use 'ng-hub-ui-badges/styles' as hub;

.hub-badge {
	@include hub.hub-badge-variant-rules(
		'brand',
		$accent: #7c3aed,
		$bg: #ede9fe, // --hub-badge-bg
		$fg: #5b21b6, // --hub-badge-color
		$border: #c4b5fd, // --hub-badge-border-color
		$subtle: #ede9fe // --hub-badge-accent-subtle
	);
}

Then use any of them from Angular with color="brand".

Styling

The public token family includes:

• --hub-badge-font-size
• --hub-badge-padding-x
• --hub-badge-padding-y
• --hub-badge-border-radius
• --hub-badge-gap
• --hub-badge-direction
• --hub-badge-align
• --hub-badge-accent
• --hub-badge-accent-subtle
• --hub-badge-accent-emphasis
• --hub-badge-accent-border
• --hub-badge-dot-size
• --hub-badge-remove-size

See docs/css-variables-reference.md for the full reference.

Changelog

See CHANGELOG.md.

Contributing

Contributions and collaboration are welcome.

• Fork the repository.
• Create a feature branch.
• Commit and push your changes.
• Open a pull request.

Support

If you find this project helpful and would like to support its development, you can buy me a coffee:

• Issues: GitHub Issues
• Author: Carlos Morcillo

License

This project is licensed under the MIT License.