Badge Component

The React Badge component is provided by the platform-specific Ignite UI for React package and is used in conjunction with avatars, navigation menus, or other components in an application when a visual notification is needed. Badges are usually designed with predefined styles to communicate information, success, warnings, or errors.

Live Demo

The React Badge demo shows how the component can communicate a compact status or notification next to another interface element.

Anatomy

The React Badge presents a compact label or dot indicator that decorates another interface element.

The component renders its content inside the base CSS part. Use the component’s default slot for text or other inline content; when dot is enabled, the badge renders as an indicator without content.

<igc-badge>
└── ::part(base)
  └── default slot content
</igc-badge>

Getting Started

To use the React Badge, follow the Ignite UI for React Getting Started topic for the basic project setup, then register the component for your target platform.

Prerequisites and Version Compatibility

Use a supported version of the Ignite UI for React package for your target framework. Keep the framework package, the Badge package, and the theme package on the same release version. The examples below identify the framework and package used by each code block so that the snippets remain self-contained when read without the surrounding page context.

For React using the igniteui-react package, install the package:

npm install igniteui-react

You will then need to import the Badge wrapper and its theme CSS, like so:

import { IgrBadge } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

<IgrBadge />

Usage

Use the React Badge to display a short status, category, count, or notification indicator alongside another component.

The following example shows a success Badge displayed on an Avatar. Import the Badge and Avatar components from the platform-specific package, then place the Badge inside a relatively positioned wrapper.

import { IgrAvatar, IgrBadge } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

Add the components to your JSX:

<div className="wrapper">
  <IgrAvatar icon="person" shape="circle" size="small"></IgrAvatar>
  <IgrBadge icon="check" variant="success"></IgrBadge>
</div>

Use a relatively positioned wrapper to place the Badge over the Avatar:

.wrapper {
  position: relative;
  margin-top: 15px;
}

Type

The Ignite UI for React Badge can carry different types of content, such as a number or an icon.

Use the value property to display text or a numeric count inside the Badge:

<IgrBadge variant="primary">12</IgrBadge>

You can also project content directly. When projecting both an icon and text, wrap the text to keep the correct padding.

<IgrBadge>
  <IgrIcon name="bluetooth" />
  <span>Bluetooth</span>
</IgrBadge>

Icon

Add an icon as child content inside the Badge:

<IgrBadge variant="success">
  <IgrIcon name="heart-monitor" />
</IgrBadge>

For custom icons, register the icon with the platform’s icon service and render it as child content inside the Badge.

For example, register an SVG icon before using it in the Badge:

import { registerIconFromText } from 'igniteui-webcomponents';

registerIconFromText(
  'heart-monitor',
  '<svg viewBox="0 0 24 24"><path d="M3 12h4l2-6 4 12 2-6h6" /></svg>',
  'custom'
);

Dot

The Ignite UI for React Badge can also render as a minimal dot indicator for notifications by setting its dot attribute. Dot badges do not support content, but they can be outlined and can use any of the available dot types (for example, primary, success, or info).

Set the dot attribute to render a minimal notification indicator without content:

<IgrBadge dot={true} ></IgrBadge>

Size

Control the Badge size with the --size CSS variable. For text badges smaller than 16px, also adjust the font size and line height:

igc-badge {
  --size: 12px;

  font-size: calc(var(--size) / 2);
  line-height: normal;
}

Shape

The badge component supports rounded(default) and square shapes. These values can be assigned to the Shape attribute.

<IgrBadge shape="square" ></IgrBadge>

When the badge has a square shape, it can be further customized by setting a custom border radius using the --border-radius CSS variable.

Variants

The Ignite UI for React Badge supports several pre-defined stylistic variants (Primary, Info, Success, Warn, and Error). Assign one of the supported values — primary, info, success, warning, or danger — to the variant attribute.

<IgrBadge variant="success" ></IgrBadge>

Outlined

The badge can also have a subtle border around it when the outlined attribute is set.

<IgrBadge outlined={true} ></IgrBadge>

The border color of the outlined badge can also be customized using the --border-color CSS variable.

Do/Don’t

When to use: Use a Badge to communicate a short status, category, count, or notification state alongside another component. Use dot when the indicator does not need visible text.

When not to use: Do not use a Badge as the primary control for an action, as a replacement for a form validation message, or when the status cannot be understood from the badge content, surrounding context, or accessible labeling.

Do	Don’t

Properties

The React Badge exposes platform-specific properties for controlling its content, appearance, and indicator behavior.

The React Badge exposes the following properties.

Styling

The React Badge uses the IgrBadge component’s base CSS part and documented styling variables to customize its appearance.

Sass Theming

Use the Ignite UI for React theme system to style the Badge consistently with the rest of your application.

CSS Variables

igc-badge::part(base) {
  --background-color: var(--ig-error-A100);
  --border-radius: 2px;
}

Style Parts

Styling with Tailwind

You can style the Badge with the custom Tailwind utility classes from igniteui-theming. Make sure to set up Tailwind first, then import the Ignite UI utilities in your global stylesheet:

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

<IgrBadge className="!light-badge ![--background:#FF4E00] ![--border-radius:4px]"></IgrBadge>

The exclamation mark (!) gives the Tailwind utility precedence over the Badge’s default theme styles.

Accessibility

The React Badge is a non-interactive status visual that communicates a short count, state, or notification.

Keyboard Interaction

The Badge does not receive focus, handle keyboard input, or expose component interaction events.

Screen Readers / ARIA

The Badge host uses role="status" to expose its content as status information.

• The component sets aria-roledescription to identify the Badge and its current variant.
• Add an aria-label when a Badge without text, including a dot Badge, communicates status that is not otherwise available to assistive technology.
• Keep the Badge content or accessible label specific to the decorated item, such as 3 unread messages rather than only 3.

Accessibility Compliance

Infragistics documents Ignite UI for React accessibility support for Section 508 and WCAG 2.1 guideline areas in the Accessibility Compliance topic.

Your responsibilities:

• Provide an accessible name that explains the status when the Badge has no meaningful text, especially for dot Badges.
• Do not use Badge color as the only indication of status; pair it with text, an icon, or another accessible cue.
• Keep sufficient contrast between the Badge foreground and background when overriding theme styles.

Troubleshooting

The React Badge troubleshooting guidance follows a problem → cause → fix format for common styling and content issues.

Why does my custom background color not change the Badge?

The selected variant takes precedence over the --background-color CSS variable. To use a custom background color, avoid setting a variant that applies its own background color.

Why is my dot Badge not displaying content?

The dot property renders the Badge as a minimal indicator and does not support content. Use a regular Badge when you need to display text or other inline content.

Known Limitations

The React Badge has the following platform-independent limitations.

• A dot Badge is an indicator only and cannot display text or an icon.
• Badge styling and variant/type names differ between Angular and the other supported frameworks. Use the platform-specific examples and API links on this page rather than copying an attribute between frameworks.
• The Badge is a visual status indicator and does not provide keyboard interaction of its own.

API References

Dependencies

The React Badge requires a theme stylesheet to apply its visual styling. See the framework-specific setup in Getting Started.

Additional Resources

The following resources provide additional React Badge guidance and project support.

• Ignite UI for React Forums
• Ignite UI for React GitHub

Related Components

The React Badge is commonly used with related components such as Avatar when a status indicator belongs to another visual element.

• Avatar — combine an Avatar with a Badge to show a status indicator.

FAQ

These frequently asked questions cover common React Badge content, indicator, and package choices.