@versini/ui-badge

An inline, superscript-style React badge for adding a small red dot or a count to any piece of text.

The Badge component renders a <sup> element that sits next to text — like a native <sup> tag — and displays either a small red dot (notification indicator) or a count (with a 99+ ceiling for large numbers). Its size automatically scales with the surrounding font, so it works inside any text element (<h1>, <p>, <button>, etc.) without manual tuning.

Installation

npm install @versini/ui-badge

Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

Number badge

import { Badge } from "@versini/ui-badge";

function App() {
  return (
    <p>
      Notifications <Badge>42</Badge>
    </p>
  );
}

Dot badge

import { Badge } from "@versini/ui-badge";

function App() {
  return (
    <p>
      Profile <Badge />
    </p>
  );
}

Counts above 99

<p>
  Inbox <Badge>250</Badge>
</p>
// renders "99+"

Auto-scaling with the parent font-size

<h1>Messages <Badge>3</Badge></h1>
<p>Messages <Badge>3</Badge></p>

The badge's font-size and dimensions are expressed in em units, so the badge naturally scales with the text it's attached to.

Fine-tuning position

Inside flex containers (menu items, buttons with icons, list rows), the default vertical-align: super may pull the badge higher than ideal. Use offsetX and offsetY to nudge it back into place.

// inside a flex menu item — bring the badge down to roughly cap-height
<MenuItem label={<>Inbox <Badge offsetY="0.4em">12</Badge></>} />

// nudge a dot slightly right
<Badge offsetX="0.2em" />

// numbers default to em units (negative shifts up/left)
<Badge offsetX={0.1} offsetY={-0.1}>42</Badge>

API

Badge Props

| Prop | Type | Default | Description | | --------- | ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | children | number \| string | - | The count to display. If omitted, a small red dot is rendered. 0 (number or string) renders nothing. Non-numeric strings also render nothing. | | className | string | - | CSS class(es) to add to the badge element. | | offsetX | number \| string | - | Horizontal nudge via CSS translateX. Numbers are em units; strings pass through as-is ("2px", "-0.1em"). Negative shifts left. | | offsetY | number \| string | - | Vertical nudge via CSS translateY. Same unit rules as offsetX. Negative shifts up (toward the superscript position), positive shifts toward the baseline. |