Badge Component

The Badge component is a versatile UI element for displaying text, counts, notification dots, and icons. Supports multiple sizes, rounded shapes, colors, and click interactions.

Import Component From Library

javascript

1import { Badge } from "@neuctra/ui";

Basic Usage Code

Start with a simple badge. The component supports text, icons, notification dots, and various sizes and variants for different use cases.

jsx

1import { Badge } from '@neuctra/ui';
2
3function BasicExample() {
4  return (
5    <Badge
6      text="New"
7      variant="solid"
8      size="md"
9    />
10  );
11}

Basic Example

New

Advanced Usage

Messages

Alerts

Admin

Variants

SolidOutlineSoft

Props Table

All available props for the Badge component.

Prop	Type	Default	Description
text	string	—	Text displayed inside the badge
icon	React.ReactNode	—	Optional icon displayed alongside the text
variant	"solid" \| "outline" \| "soft"	"solid"	Controls the visual style of the badge. solid: filled • outline: bordered • soft: subtle background
iconPosition	"left" \| "right"	"left"	Position of the icon relative to the text
size	"sm" \| "md" \| "lg"	"md"	Size of the badge (affects padding and font size)
rounded	boolean	true	Whether the badge should be fully rounded (pill shape) or slightly rounded
notificationDot	boolean	false	Shows a small notification dot in the top-right corner
dotColor	string	—	Present in the prop types but not currently wired up — the dot always renders in the destructive color. Use `dotStyle` or `dotClassName` to change it.
count	number \| string	—	Displays a numeric or custom count badge (e.g., unread messages)
pulse	boolean	false	Enables a pulsing animation on the notification dot
onClick	() => void	—	Click handler. Makes the badge interactive with hover effect
className	string	—	Additional CSS classes for the badge container
style	CSSProperties	—	Inline styles for the badge container
dotClassName	string	—	Additional classes for the notification dot
dotStyle	CSSProperties	—	Inline styles for the notification dot
countClassName	string	—	Additional classes for the count badge
countStyle	CSSProperties	—	Inline styles for the count badge
iconClassName	string	—	Additional classes for the icon wrapper
iconStyle	CSSProperties	—	Inline styles for the icon wrapper
textClassName	string	—	Additional classes for the text label
textStyle	CSSProperties	—	Inline styles for the text label

Common Mistakes

<Badge notificationDot count={5} />

Using both notificationDot and count at the same time can cause visual overlap.

<Badge primaryColor="..." />

The primaryColor prop does not exist. Use className or style to customize colors.

<Badge dotColor="#ef4444" notificationDot />

dotColor is defined in props but currently not used in the component. Use dotStyle or dotClassName instead.

<Badge text="New" icon={<Bell />} count={12} pulse />

Combining icon, count, and pulse creates highly noticeable badges.

Pro Tips

Use count for numeric indicators like unread messages or notifications.
Combine icon with iconPosition for better context (e.g., status badges).
Use notificationDot + pulse for urgent alerts.
Customize appearance using className and style since the component uses Tailwind + CSS variables.
Choose rounded= when you need a more rectangular badge shape.
Keep text short — badges are meant to be compact.
For clickable badges, ensure sufficient contrast and clear labeling for accessibility.

Frequently Asked Questions

How do I install and import the Badge component?

Install the @neuctra/ui package, then import it with: import { Badge } from "@neuctra/ui";

What variants and sizes does Badge support?

Badge supports variants: solid, outline, soft and sizes: sm, md, lg. Use the variant and size props to switch between them, or pass a className to layer on custom Tailwind CSS classes.

Is the Badge component accessible?

Badge is built with semantic HTML and standard ARIA attributes, and supports keyboard navigation and focus states out of the box, so it works well with screen readers and keyboard-only users.