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.

import IconButton from '@mui/material/IconButton';
import Badge from '@mui/material/Badge';
import MailIcon from '@mui/icons-material/Mail';

const maxVisibleNotifications = 99;
const unreadNotificationsCount = 100;

function getUnreadNotificationsLabel(count: number) {
  if (count === 0) {
    return 'show no unread notifications';
  }
  if (count > maxVisibleNotifications) {
    return `show more than ${maxVisibleNotifications} unread notifications`;
  }
  return `show ${count} unread notification${count === 1 ? '' : 's'}`;
}

export default function BadgeIntro() {
  const label = getUnreadNotificationsLabel(unreadNotificationsCount);

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

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.

import Badge from '@mui/material/Badge';
import List from '@mui/material/List';
import ListItemButton from '@mui/material/ListItemButton';
import ListItemIcon from '@mui/material/ListItemIcon';
import ListItemText from '@mui/material/ListItemText';
import Paper from '@mui/material/Paper';
import DraftsIcon from '@mui/icons-material/Drafts';
import InboxIcon from '@mui/icons-material/Inbox';
import SendIcon from '@mui/icons-material/Send';

const unreadMessagesCount = 4;

export default function BadgeListItem() {
  return (
    <Paper variant="outlined" sx={{ width: 320, maxWidth: '100%' }}>
      <List component="nav" aria-label="mail folders" sx={{ py: 0 }}>
        <ListItemButton
          selected
          aria-current="page"
          aria-label={`Inbox, ${unreadMessagesCount} unread messages`}
        >
          <ListItemIcon>
            <Badge badgeContent={unreadMessagesCount} color="primary">
              <InboxIcon />
            </Badge>
          </ListItemIcon>
          <ListItemText primary="Inbox" />
        </ListItemButton>
        <ListItemButton>
          <ListItemIcon>
            <SendIcon />
          </ListItemIcon>
          <ListItemText primary="Sent" />
        </ListItemButton>
        <ListItemButton>
          <ListItemIcon>
            <DraftsIcon />
          </ListItemIcon>
          <ListItemText primary="Drafts" />
        </ListItemButton>
      </List>
    </Paper>
  );
}

Badge content

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

import Badge from '@mui/material/Badge';
import IconButton from '@mui/material/IconButton';
import MailIcon from '@mui/icons-material/Mail';

export default function SimpleBadge() {
  return (
    <IconButton aria-label="show 4 unread messages">
      <Badge badgeContent={4} color="primary">
        <MailIcon />
      </Badge>
    </IconButton>
  );
}

Dot badge

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

import IconButton from '@mui/material/IconButton';
import Badge from '@mui/material/Badge';
import NotificationsIcon from '@mui/icons-material/Notifications';

export default function DotBadge() {
  return (
    <IconButton aria-label="show new notifications">
      <Badge color="secondary" variant="dot">
        <NotificationsIcon />
      </Badge>
    </IconButton>
  );
}

Visibility

Control badge visibility with the invisible prop.

Show unread count

import * as React from 'react';
import Stack from '@mui/material/Stack';
import Badge from '@mui/material/Badge';
import IconButton from '@mui/material/IconButton';
import Switch from '@mui/material/Switch';
import FormControlLabel from '@mui/material/FormControlLabel';
import MailIcon from '@mui/icons-material/Mail';

const unreadMessagesCount = 4;

export default function BadgeVisibility() {
  const [invisible, setInvisible] = React.useState(false);

  const handleBadgeVisibility = () => {
    setInvisible((previousInvisible) => !previousInvisible);
  };

  return (
    <Stack direction="row" spacing={3} sx={{ alignItems: 'center' }}>
      <IconButton
        aria-label={
          invisible
            ? 'open inbox'
            : `open inbox, ${unreadMessagesCount} unread messages`
        }
      >
        <Badge
          color="secondary"
          badgeContent={unreadMessagesCount}
          invisible={invisible}
        >
          <MailIcon />
        </Badge>
      </IconButton>
      <FormControlLabel
        control={<Switch checked={!invisible} onChange={handleBadgeVisibility} />}
        label="Show unread count"
      />
    </Stack>
  );
}

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

import Stack from '@mui/material/Stack';
import Badge from '@mui/material/Badge';
import IconButton from '@mui/material/IconButton';
import MailIcon from '@mui/icons-material/Mail';

export default function ShowZeroBadge() {
  return (
    <Stack spacing={2} direction="row">
      <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>
    </Stack>
  );
}

Maximum value

Use the max prop to cap large numeric values.

import Stack from '@mui/material/Stack';
import Badge from '@mui/material/Badge';
import IconButton from '@mui/material/IconButton';
import MailIcon from '@mui/icons-material/Mail';

export default function BadgeMax() {
  return (
    <Stack spacing={2} direction="row">
      <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>
    </Stack>
  );
}

Customization

Color

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

import Badge from '@mui/material/Badge';
import Stack from '@mui/material/Stack';
import IconButton from '@mui/material/IconButton';
import CalendarMonthIcon from '@mui/icons-material/CalendarMonth';
import FolderOpenIcon from '@mui/icons-material/FolderOpen';
import ReportProblemOutlinedIcon from '@mui/icons-material/ReportProblemOutlined';

export default function ColorBadge() {
  return (
    <Stack spacing={2} direction="row">
      <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>
    </Stack>
  );
}

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.

import Box from '@mui/material/Box';
import Stack from '@mui/material/Stack';
import Badge from '@mui/material/Badge';

const shapeSize = 32;

export default function BadgeOverlap() {
  return (
    <Stack spacing={3} direction="row">
      <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>
    </Stack>
  );
}

function Rectangle() {
  return (
    <Box
      component="span"
      sx={{ bgcolor: 'primary.main', width: shapeSize, height: shapeSize }}
    />
  );
}

function Circle() {
  return (
    <Box
      component="span"
      sx={{
        bgcolor: 'primary.main',
        width: shapeSize,
        height: shapeSize,
        borderRadius: '50%',
      }}
    />
  );
}

Custom styles

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

import Badge from '@mui/material/Badge';
import Avatar from '@mui/material/Avatar';
import List from '@mui/material/List';
import ListItemAvatar from '@mui/material/ListItemAvatar';
import ListItemButton from '@mui/material/ListItemButton';
import ListItemText from '@mui/material/ListItemText';
import Paper from '@mui/material/Paper';
import { styled } from '@mui/material/styles';

type ContactStatus = 'online' | 'offline';

const statusLabels: Record<ContactStatus, string> = {
  online: 'Online',
  offline: 'Offline',
};

const contacts = [
  { name: 'Remy Sharp', initials: 'R', status: 'online' },
  { name: 'Travis Howard', initials: 'T', status: 'offline' },
  { name: 'Cindy Baker', initials: 'C', status: 'online' },
] as const;

const ContactStatusBadge = styled(Badge, {
  shouldForwardProp: (prop) => prop !== 'status',
})<{ status: ContactStatus }>(({ theme, status }) => {
  const themePalette = (theme.vars ?? theme).palette;
  const offlineBadgeColor = theme.vars
    ? theme.vars.palette.Avatar.defaultBg
    : theme.palette.grey[400];

  return {
    '& .MuiBadge-badge': {
      height: 10,
      minWidth: 10,
      border: `1px solid ${themePalette.grey[300]}`,
      boxShadow: `0 0 0 2px ${themePalette.background.paper}`,
      ...(status === 'offline' && {
        backgroundColor: offlineBadgeColor,
        ...(theme.vars
          ? {}
          : theme.applyStyles('dark', {
              backgroundColor: theme.palette.grey[600],
            })),
      }),
    },
  };
});

export default function CustomizedBadges() {
  return (
    <Paper variant="outlined" sx={{ width: 320, maxWidth: '100%' }}>
      <List component="nav" aria-label="contacts" sx={{ py: 0 }}>
        {contacts.map((contact) => {
          const statusLabel = statusLabels[contact.status];

          return (
            <ListItemButton
              key={contact.name}
              aria-label={`${contact.name}, ${contact.status}`}
            >
              <ListItemAvatar>
                <ContactStatusBadge
                  status={contact.status}
                  color={contact.status === 'online' ? 'success' : 'default'}
                  variant="dot"
                  overlap="circular"
                  anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
                >
                  <Avatar>{contact.initials}</Avatar>
                </ContactStatusBadge>
              </ListItemAvatar>
              <ListItemText primary={contact.name} secondary={statusLabel} />
            </ListItemButton>
          );
        })}
      </List>
    </Paper>
  );
}

API

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

<Badge />