Badge
An unstyled badge component for displaying status indicators.
Build fully custom status indicators with complete control over layout and styling.
25128
basic-demo
Pre-styled Versions
Choose a pre-styled library to use Badge with ready-made designs.
For hook-based usage without components, see the Headless API.
Features#
- Single
Badgecomponent withOverlayBadgefor positioned overlays - Dot indicator via empty children — renders as a small status dot when no content is provided
Usage#
import { Badge } from 'primereact/badge';
import { OverlayBadge } from 'primereact/overlaybadge';<Badge></Badge>
<OverlayBadge>
<IconComponent />
<Badge></Badge>
</OverlayBadge>Behavior#
Polymorphic Rendering#
Use as on Badge or OverlayBadge to change the rendered HTML element.
<Badge as="div">4</Badge>
<OverlayBadge as="span">...</OverlayBadge>Default elements: Badge=span, OverlayBadge=div.
Render Function Children#
Badge accepts a render function as children, providing access to the component instance.
<Badge>{(instance) => <span>Count</span>}</Badge>Pass Through#
Some parts may not be visible in the preview depending on the component's current state.
Badge
/* Select a part to see its CSS selector for custom styling */API#
Badge#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: BadgeInstance) => CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: BadgeInstance) => string) | — |
| The class name to apply to the component. | ||
as | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | BadgeInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<BadgePassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: BadgeInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
shape | "circle" | — |
| Defines the shape of the badge. | ||
size | "small" | "large" | "xlarge" | — |
| Size of the badge. | ||
severity | "secondary" | "info" | "success" | "warn" | "danger" | "contrast" | — |
| Severity type of the badge. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
| Attribute | Value |
|---|---|
data-scope | "badge" |
data-part | "root" |
data-empty | Present when badge has no children |
Defines passthrough(pt) options of Badge component.
| label | type | description |
|---|---|---|
| root | BadgePassThroughType<HTMLAttributes<HTMLSpanElement>> | Used to pass attributes to the root's DOM element. |
OverlayBadge#
| Name | Type | Default |
|---|---|---|
ref | Ref<unknown> | — |
| The reference to the component instance. | ||
pIf | boolean | true |
| Whether the component should be rendered. | ||
style | CSSProperties | ((instance?: OverlayBadgeInstance) => CSSProperties) | — |
| The style to apply to the component. | ||
className | string | ((instance?: OverlayBadgeInstance) => string) | — |
| The class name to apply to the component. | ||
as | string | number | bigint | boolean | ComponentClass<any, any> | FunctionComponent<any> | ReactElement<unknown, string | JSXElementConstructor<any>> | Iterable<ReactNode, any, any> | ReactPortal | Promise<AwaitedReactNode> | — |
| The component type to render. | ||
asChild | boolean | false |
| Whether the component should be rendered as a child component. | ||
instance | OverlayBadgeInstance | — |
| The instance to pass to the component. | ||
pt | SafeRecord<OverlayBadgePassThrough> | — |
| The pass-through props to pass to the component. | ||
ptOptions | PassThroughOptions | — |
| The pass-through options to pass to the component. | ||
unstyled | boolean | — |
| Whether the component should be rendered without classes. | ||
dt | unknown | — |
| The design token to use for the component. | ||
styles | StylesOptions<ComponentInstance> | — |
| The styles to use for the component. | ||
render | (instance: OverlayBadgeInstance) => ReactNode | — |
| The render function to render the component with instance access. | ||
children | any | — |
| The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates. | ||
[key: string] | any | — |
pt-{optionName}-* | - | — |
| Pass through attributes for customizing component. For more info, see Pass Through tab. | ||
Defines passthrough(pt) options of OverlayBadge component.
| label | type | description |
|---|---|---|
| root | OverlayBadgePassThroughType<HTMLAttributes<HTMLDivElement>> | Used to pass attributes to the root's DOM element. |
Accessibility#
Screen Reader#
Badge does not include any roles and attributes by default. Any attribute is passed to the root element so aria-label or aria-live can be added if badges are dynamic. In case badges need to be tabbable, tabIndex can be added to implement custom key handlers.
Keyboard Support#
Component does not include any interactive elements.