Badge

Badge generates a small badge to the top-right of its child(ren).

Usage guidelines

Use badges for supplemental status: Use badges for short counts or compact states that update an existing control or item, such as unread messages on an inbox button. If the status is important on its own, show it in the UI instead of relying only on the badge.
Label the element that owns the badge: A badge is a visual cue tied to another element, so its meaning should be part of that element's accessible name. For example, use aria-label="Inbox, 4 unread messages" instead of aria-label="Inbox" on the target element.
Use dot badges for simple states: A dot badge does not show text or a number, so use it only when the surrounding UI makes the state clear, such as Online or Unread.

Edit code

<IconButton aria-label={label}>
  <Badge
    badgeContent={unreadNotificationsCount}
    color="secondary"
    max={maxVisibleNotifications}
  >
    <MailIcon />
  </Badge>
</IconButton>

<IconButton aria-label={label}>
  <Badge
    badgeContent={unreadNotificationsCount}
    color="secondary"
    max={maxVisibleNotifications}
  >
    <MailIcon />
  </Badge>
</IconButton>

Press Enter to start editing

This demo applies the same pattern to a ListItemButton with a Badge: the visible count is included in the item's accessible name so it's announced in the context of the surrounding UI.

Badge content

Use badgeContent to add a short count or label to the wrapped element.

Edit code

<IconButton aria-label="show 4 unread messages">
  <Badge badgeContent={4} color="primary">
    <MailIcon />
  </Badge>
</IconButton>

<IconButton aria-label="show 4 unread messages">
  <Badge badgeContent={4} color="primary">
    <MailIcon />
  </Badge>
</IconButton>

Press Enter to start editing

Dot badge

Use variant="dot" for a compact status indicator without a count.

Edit code

<IconButton aria-label="show new notifications">
  <Badge color="secondary" variant="dot">
    <NotificationsIcon />
  </Badge>
</IconButton>

<IconButton aria-label="show new notifications">
  <Badge color="secondary" variant="dot">
    <NotificationsIcon />
  </Badge>
</IconButton>

Press Enter to start editing

Visibility

Control badge visibility with the invisible prop.

Show unread count

The badge hides automatically when badgeContent is zero. Override this with the showZero prop when zero is meaningful to the interface.

Edit code

<IconButton aria-label="show no unread messages">
  <Badge color="secondary" badgeContent={0}>
    <MailIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show 0 unread messages">
  <Badge color="secondary" badgeContent={0} showZero>
    <MailIcon />
  </Badge>
</IconButton>

<IconButton aria-label="show no unread messages">
  <Badge color="secondary" badgeContent={0}>
    <MailIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show 0 unread messages">
  <Badge color="secondary" badgeContent={0} showZero>
    <MailIcon />
  </Badge>
</IconButton>

Press Enter to start editing

Maximum value

Use the max prop to cap large numeric values.

Edit code

<IconButton aria-label="show 99 unread messages">
  <Badge color="secondary" badgeContent={99}>
    <MailIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show more than 99 unread messages">
  <Badge color="secondary" badgeContent={100}>
    <MailIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show more than 999 unread messages">
  <Badge color="secondary" badgeContent={1000} max={999}>
    <MailIcon />
  </Badge>
</IconButton>

<IconButton aria-label="show 99 unread messages">
  <Badge color="secondary" badgeContent={99}>
    <MailIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show more than 99 unread messages">
  <Badge color="secondary" badgeContent={100}>
    <MailIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show more than 999 unread messages">
  <Badge color="secondary" badgeContent={1000} max={999}>
    <MailIcon />
  </Badge>
</IconButton>

Press Enter to start editing

Customization

Color

Use the color prop to apply theme palette colors to the badge.

Edit code

<IconButton aria-label="show 8 shared files">
  <Badge badgeContent={8} color="primary">
    <FolderOpenIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show 2 confirmed events">
  <Badge badgeContent={2} color="success">
    <CalendarMonthIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show 1 critical alert">
  <Badge badgeContent={1} color="error">
    <ReportProblemOutlinedIcon />
  </Badge>
</IconButton>

<IconButton aria-label="show 8 shared files">
  <Badge badgeContent={8} color="primary">
    <FolderOpenIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show 2 confirmed events">
  <Badge badgeContent={2} color="success">
    <CalendarMonthIcon />
  </Badge>
</IconButton>
<IconButton aria-label="show 1 critical alert">
  <Badge badgeContent={1} color="error">
    <ReportProblemOutlinedIcon />
  </Badge>
</IconButton>

Press Enter to start editing

Badge alignment

Use the anchorOrigin prop to move the badge to any corner of the wrapped element.

Vertical

TopBottom

Horizontal

RightLeft

<IconButton aria-label="show 12 unread messages">
  <Badge
    badgeContent={12}
    color="secondary"
    anchorOrigin={{
      vertical: 'top',
      horizontal: 'right',
    }}
  >
    <MailIcon />
  </Badge>
</IconButton>

Badge overlap

Use the overlap prop when the wrapped element is circular.

Edit code

<Badge color="secondary" badgeContent={1}>
  <Rectangle />
</Badge>
<Badge color="secondary" variant="dot">
  <Rectangle />
</Badge>
<Badge color="secondary" overlap="circular" badgeContent={1}>
  <Circle />
</Badge>
<Badge color="secondary" overlap="circular" variant="dot">
  <Circle />
</Badge>

<Badge color="secondary" badgeContent={1}>
  <Rectangle />
</Badge>
<Badge color="secondary" variant="dot">
  <Rectangle />
</Badge>
<Badge color="secondary" overlap="circular" badgeContent={1}>
  <Circle />
</Badge>
<Badge color="secondary" overlap="circular" variant="dot">
  <Circle />
</Badge>

Press Enter to start editing

Custom styles

Use theme style overrides, the sx prop, or styled() to customize the badge. Learn more in the customization guide.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<Badge />