Badge

Badge is a compact, themed label built on Roblox's native ImageLabel. It shows a count, status, or short piece of text, optionally preceded by an icon, and sizes itself to its content.

Import

import { Badge } from "@rbxts/react-clean-ui";

Basic usage

The text prop is required and renders the label.

<Badge text="New" />
<Badge text="12" intent="danger" />

Intents

Set intent to control the badge's background, border, and text/icon colors. When intent is omitted, primary is used.

<Badge text="Primary" intent="primary" />
<Badge text="Secondary" intent="secondary" />
<Badge text="Success" intent="success" />
<Badge text="Info" intent="info" />
<Badge text="Warning" intent="warning" />
<Badge text="Danger" intent="danger" />

In the default theme, primary is a neutral light-grey pill with dark text, while the other intents use solid intent-colored backgrounds with white text.

Icons

Set icon to draw an icon before the text. The icon is tinted with the same color as the text.

The gap between the icon and the text is half of the resolved spacing at the badge's scale, rounded up, the same gap HStack uses by default.

Scaling

Badge supports the shared scale prop, which moves the text size, icon size, padding, and icon/text gap together.

Available scales are xs, sm, md, lg, and xl. When scale is not provided, the component uses theme.default.scale.

Placing a badge

Badge sizes to its content and never stretches to fill its parent, so it sits naturally next to other content in a stack. Use LayoutOrder to order it inside a layout.

Outside a layout, set Position and AnchorPoint to place the badge yourself.

<Badge
    text="Live"
    intent="danger"
    scale="xs"
    Position={new UDim2(1, -4, 0, 4)}
    AnchorPoint={new Vector2(1, 0)}
/>

Theming

Badge has no color, padding, or size props of its own; its look comes entirely from theme.components.badge. Use createTheme (or extendTheme) to change it theme-wide, then apply it with ThemeProvider.

import { Badge, createTheme, ThemeProvider } from "@rbxts/react-clean-ui";

const themeWithSquareBadges = createTheme({
    components: {
        badge: {
            cornerRadius: "4px",
            borderThickness: 0,
            padding: "2px 8px",
            intents: {
                danger: {
                    default: {
                        textColor: Color3.fromHex("#FFFFFF"),
                        backgroundColor: Color3.fromHex("#B91C1C"),
                        borderColor: Color3.fromHex("#B91C1C"),
                    },
                },
            },
        },
    },
});

<ThemeProvider theme={themeWithSquareBadges}>
    <Badge text="Offline" intent="danger" />
</ThemeProvider>

Set backgroundColor, borderColor, and textColor for every intent you customize. The component's primary entry is layered over each intent's theme colors, so any field left unset on an intent can inherit primary's neutral pill colors.

Props

Badge-specific props

Shared props

The badge also supports props inherited from the following interfaces.

Behaviour

• The badge sizes to its content (AutomaticSize.XY with a zero base size) and never stretches to its parent's width.
• The badge never takes input: its ImageLabel has Active and Selectable set to false, and no events are wired. There are no hover or disabled states; colors always resolve from the intent's default state.
• Content is laid out left to right and vertically centered, without wrapping: the optional icon first, then the text. Text wrapping is disabled.
• An inner border stroke only renders when the theme's borderThickness is greater than 0.
• When the resolved intent has no backgroundImage, the image is cleared (Image=""), so a flat badge never shows a stale image.
• The ref forwards to the root ImageLabel.

Theme values

The badge uses values from theme.components.badge for:

• cornerRadius — the corner radius ("50%" for a pill in the default and dark themes, "4px" in Sandstone and Wooden)
• borderThickness — the inner border thickness; 0 renders no border
• spacing / padding (optional) — internal padding, resolved per badge scale (not theme.default.spacing). The default theme uses per-scale padding from "1px 4px" (xs) to "6px 14px" (xl)
• typography (optional) — a plain partial typography style or a per-scale one, merged over the theme typography for the badge's scale. The default theme uses bold text from Size10 (xs) to Size24 (xl), with no font so each theme keeps its own
• intents (optional) — per-intent textColor, backgroundColor, borderColor, backgroundTransparency, backgroundImage, and backgroundGradient, layered on top of theme.colors.intents

These values can be changed by providing a custom Clean UI theme.