Skip to main content


A Badge is a small component typically used to communicate a numerical value or indicate the status of an item to the user.


Pearl UI exports 2 badge-related components:

  1. Badge: A single badge which displays a numerical value or an icon.
  2. withBadge: A higher-order component which can be used to add a badge to any target component.
import { withBadge, Badge } from "pearl-ui";


// Adds a numerical value to the badge<Badge>23</Badge>;
// Adds an icon to the badgeimport { Icon } from "pearl-ui";
<Badge>  <Icon iconFamily="Entypo" iconName="edit" color="neutral.50" size="s"></Icon></Badge>;

Badge sizes#

Use the size prop to change the size of the badge. You can set the value to the keys available in PearlTheme.components.Badge["sizes"], which are "s", "m", "l", and "xl" in the default theme.

<Badge size="s">234+</Badge>
<Badge size="m">234+</Badge>
<Badge size="l">234+</Badge>
<Badge size="xl">234+</Badge>

Badge variants#

Use the variant prop to change the type of badge used. You can set the value to the keys available in PearlTheme.components.Badge["variants"], which are "rounded" and "square" in the default theme.

<Badge variant="rounded">2</Badge>
<Badge variant="square">NEW</Badge>

Badge color scheme#

Use the colorScheme prop to change the color palette of the badge.

You can set the value only to the keys available in PearlTheme.palette that contain a palette of colors represented as an object, which are "primary", "secondary", "neutral", etc in the default Pearl theme.

<Badge colorScheme="primary" />
<Badge colorScheme="success" />
<Badge colorScheme="warning" />
<Badge colorScheme="info" />
<Badge colorScheme="danger" />

Attaching badges to other components#

The true power of Badge is revealed when it is coupled with other components. The withBadge function allows you to add a badge to any React component is an extremely simple manner, while provoding you the freedom to customize at will. The list of props expected by withBadge can be found here.

This can prove helpful when dealing with common use-cases of badges such as adding a notification badge as follows:

// Attaches the badge to an Icon componentimport { Icon, IconProps } from "pearl-ui";
const numberOfNotifications = 5;
const BadgedIcon = withBadge<IconProps>(numberOfNotifications, {  placement: "topRight",  size: "s",  colorScheme: "danger",})(Icon);
return <BadgedIcon iconFamily="FontAwesome" iconName="inbox" />;

Override Style#

The Badge component also supports a variety of style props which can be used to override the pre-defined variant style in the theme. Manual style props passed into the component have a higher precedance than the default component config.

<Badge backgroundColor="blue" variant="square" mt="l" />


Badge Props#

Supported style props#

Badge composes Pressable so you can pass all Pressable related props to it.

Additional props#

sizefalsePearlTheme.components.Badge["sizes"]"m"Size of the badge.
variantfalsePearlTheme.components.Badge["variants"]"rounded"Variant of the badge.
colorSchemestringPearlTheme["palette"]"primary"Active color palette of the badge.

withBadge Props#

badgeValuetruestring | number | React.ReactElementThe value to be displayed inside the badge.
hiddenfalsebooleanA set of options for customizing the look of the badge.
optionsfalseBadgeProps | { placement: "topLeft" | "topRight" | "bottomLeft" | "bottomRight", offset: number }Whether the badge is visible or not.

Default Component Config#

export default {  parts: ["root", "text"],  baseStyle: {    root: {      backgroundColor: "primary.500",    },    text: {      color: "neutral.50",    },  },  sizes: {    s: {      root: {        minW: 20,        h: 20,      },      text: {        px: "2xs",        variant: "btn4",      },    },    m: {      root: {        minW: 25,        h: 25,      },      text: {        px: "xs",        variant: "btn4",      },    },    l: {      root: {        minW: 30,        h: 30,      },      text: {        px: "xs",        variant: "btn3",      },    },    xl: {      root: {        minW: 35,        h: 35,      },      text: {        px: "s",        variant: "btn3",      },    },  },  variants: {    rounded: {      root: {        borderRadius: "full",      },    },    square: {      root: {        borderRadius: "m",      },    },  },  defaults: {    size: "m",    variant: "rounded",  },};