ShieldBadge
shield-badgeRenders repository-style metric badges with label and value segments.
Usage
README Badge Line
ShieldBadgeGroup arranges a row of item meta information, and automatically wraps lines in narrow screens; icon places the brand mark in the slot.
<ShieldBadgeGroup>
<ShieldBadge label="@hulianui/ui" value="v0.17.0" icon={<NpmMark />} />
<ShieldBadge label="downloads" value={`${compactCount(1500)}/month`} />
<ShieldBadge label="license" value="MIT" />
<ShieldBadge label="CI" value="failing" tone="danger" icon={<GithubMark />} />
<ShieldBadge label="stars" value={compactCount(4)} />
</ShieldBadgeGroup>Tone
Right paragraph 5 tone covers the status spectrum; color escape cabin connects to any CSS color / chart-1..6.
<>
<ShieldBadge label="license" value="MIT" tone="neutral" />
<ShieldBadge label="version" value="v0.17.0" tone="brand" />
<ShieldBadge label="build" value="passing" tone="success" />
<ShieldBadge label="coverage" value="72%" tone="warning" />
<ShieldBadge label="CI" value="failing" tone="danger" />
<ShieldBadge label="chat" value="discord" color="chart-4" />
</>Skin · Appearance
solid Sticky feel (default) / soft (embedded in the text without stealing the show) / outline Stroke; shape Change to rounded corners.
<>
<ShieldBadge label="build" value="passing" tone="success" variant="soft" />
<ShieldBadge label="build" value="passing" tone="success" variant="outline" />
<ShieldBadge label="build" value="passing" tone="success" shape="pill" />
<ShieldBadge label="build" value="passing" tone="success" shape="square" />
</>Clickable · Single segment · Small size
href makes the whole piece a link (with press/focus ring); omitting label degenerates into a single segment sticker.
When to use
Use ShieldBadge in README headers, project pages, and package details for version, license, downloads, CI, and stars.
Badge overlays a count on another element, Tag is a single status label, and Chip is an interactive token. ShieldBadge represents project metadata with a distinctive two-segment structure. Use DeployStatus for deployment lifecycle, StatusDot for health, or AwardBadge for honors.
Unlike a remote shields.io image, this CSS component follows themes, avoids a request, scales cleanly, and keeps text selectable. It does not fetch data; supply the value and optionally format counts with compactCount.
Import
import { ShieldBadge, ShieldBadgeGroup, compactCount } from "@hulianui/ui"Props
ShieldBadge
| Name | Type | Default | Description |
|---|---|---|---|
| value* | ReactNode | — | Colored value segment, such as MIT, 1.5k/month, or failing. |
| label | ReactNode | — | Neutral label segment; omission creates a single-segment badge. |
| icon | ReactNode | — | Leading brand mark in the label segment, or value segment without a label. |
| tone | "neutral" | "brand" | "success" | "warning" | "danger" | "brand" | Value-segment tone. |
| color | string | — | CSS color or semantic name such as chart-1, overriding tone. |
| variant | "solid" | "soft" | "outline" | "solid" | Sticker, quiet, or outlined skin. |
| shape | "rounded" | "square" | "pill" | "rounded" | Badge shape. |
| size | "sm" | "md" | "md" | Component size. |
| href | string | — | Makes the whole badge a focusable link. |
| target | string | — | Link target; _blank adds rel="noreferrer noopener" unless explicitly overridden. |
| className | string | — | Custom class plus forwarded native attributes. |
ShieldBadgeGroup
| Name | Type | Default | Description |
|---|---|---|---|
| gap | "sm" | "md" | "sm" | Badge spacing with wrapping on narrow screens. |
compactCount(value, digits?)
Formats stars and downloads as stable badge notation such as 999, 1.5k, 12k, or 3.4M. Values at least 10 in a unit are rounded, and 999_999 carries to 1M. It deliberately avoids locale-sensitive Intl.NumberFormat compact notation.
Pitfalls
- Supply brand marks through
icon; the library does not bundle npm, GitHub, or Discord assets. Slot SVGs are sized and hidden from assistive technology. - Use Badge for an overlaid count; ShieldBadge is an inline metadata sticker.
- Solid custom colors use
--color-primary-foreground. Verify contrast for medium colors, or use the soft skin.
Related
Badge · Tag · AwardBadge · DeployStatus · GitCommit · StatusDot
Playground
<ShieldBadge
label="license"
value="MIT"
/>