Badge

The Badge component generates a small label that is attached to its child element.

Introduction

A badge is a small descriptor for UI elements. It typically sits on or near an element and indicates the status of that element by displaying a number, icon, or other short set of characters.

The Badge component creates a badge that is applied to its child element.

Component

Usage

After installation, you can start building with this component using the following basic elements:

<span class="token keyword">import</span> Badge <span class="token keyword">from</span> <span class="token string">'@mui/base/Badge'</span><span class="token punctuation">;</span>

<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">MyApp</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
  <span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Badge</span></span><span class="token punctuation">></span></span><span class="token punctuation">{</span><span class="token comment">/* the element that the badge is attached to */</span><span class="token punctuation">}</span><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Badge</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

Basics

The Badge wraps around the UI element that it's attached to. For instance, if the badge indicates the number of emails in an inbox, then the component will be structured like this:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Badge</span></span><span class="token punctuation">></span></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">MailIcon</span></span> <span class="token punctuation">/></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span><span class="token class-name">Badge</span></span><span class="token punctuation">></span></span>

Anatomy

The Badge component is composed of a root <span> that houses the element that the badge is attached to, followed by a <span> slot to represent the badge itself:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>BaseBadge-root<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
  <span class="token comment">&lt;!-- the element the badge is attached to is nested here --></span>
  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>span</span> <span class="token attr-name">class</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>BaseBadge-badge<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>badge content<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>span</span><span class="token punctuation">></span></span>
<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>span</span><span class="token punctuation">></span></span>

Custom structure

Use the slots prop to override the root or any other interior slot:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Badge</span></span> <span class="token attr-name">slots</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">root</span><span class="token operator">:</span> <span class="token string">'div'</span><span class="token punctuation">,</span> <span class="token literal-property property">badge</span><span class="token operator">:</span> <span class="token string">'div'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>

Use the slotProps prop to pass custom props to internal slots. The following code snippet applies a CSS class called my-badge to the badge slot:

<span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span><span class="token class-name">Badge</span></span> <span class="token attr-name">slotProps</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">badge</span><span class="token operator">:</span> <span class="token punctuation">{</span> <span class="token literal-property property">className</span><span class="token operator">:</span> <span class="token string">'my-badge'</span> <span class="token punctuation">}</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>

Usage with TypeScript

In TypeScript, you can specify the custom component type used in the slots.root as a generic parameter of the unstyled component. This way, you can safely provide the custom root's props directly on the component:

<span class="token operator">&lt;</span>Badge<span class="token operator">&lt;</span><span class="token keyword">typeof</span> CustomComponent<span class="token operator">></span> slots<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> root<span class="token operator">:</span> CustomComponent <span class="token punctuation">}</span><span class="token punctuation">}</span> customProp <span class="token operator">/</span><span class="token operator">></span>

The same applies for props specific to custom primitive elements:

<span class="token operator">&lt;</span>Badge<span class="token operator">&lt;</span><span class="token string">'img'</span><span class="token operator">></span> slots<span class="token operator">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> root<span class="token operator">:</span> <span class="token string">'img'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span> src<span class="token operator">=</span><span class="token string">"badge.png"</span> <span class="token operator">/</span><span class="token operator">></span>

Hook

<span class="token keyword">import</span> useBadge <span class="token keyword">from</span> <span class="token string">'@mui/base/useBadge'</span><span class="token punctuation">;</span>

The useBadge hook lets you apply the functionality of a badge to a fully custom component. It returns props to be placed on the custom component, along with fields representing the component's internal state.

Hooks do not support slot props, but they do support customization props.

Customization

Badge content

The badgeContent prop defines the content that's displayed inside the badge. When this content is a number, there are additional props you can use for further customization—see the Numerical badges section below.

The following demo shows how to create and style a typical numerical badge that's attached to a generic box element:

Badge visibility

You can control the visibility of a badge by using the invisible prop. Setting a badge to invisible does not actually hide it—instead, this prop adds the BaseBadge-invisible class to the badge, which you can target with styles to hide however you prefer:

1Show Badge

Numerical badges

The following props are useful when badgeContent is a number.

The showZero prop

By default, badges automatically hide when badgeContent={0}. You can override this behavior with the showZero prop:

<StyledBadge badgeContent={0}>
  <MailIcon />
</StyledBadge>
<StyledBadge badgeContent={0} showZero>
  <MailIcon />
</StyledBadge>

<StyledBadge badgeContent={0}>
  <MailIcon />
</StyledBadge>
<StyledBadge badgeContent={0} showZero>
  <MailIcon />
</StyledBadge>

Press Enter to start editing

The max prop

You can use the max prop to set a maximum value for badgeContent. The default is 99.

9999+999+

<StyledBadge badgeContent={99}>
  <MailIcon />
</StyledBadge>
<StyledBadge badgeContent={100}>
  <MailIcon />
</StyledBadge>
<StyledBadge badgeContent={1000} max={999}>
  <MailIcon />
</StyledBadge>

<StyledBadge badgeContent={99}>
  <MailIcon />
</StyledBadge>
<StyledBadge badgeContent={100}>
  <MailIcon />
</StyledBadge>
<StyledBadge badgeContent={1000} max={999}>
  <MailIcon />
</StyledBadge>

Press Enter to start editing

Accessibility

Screen readers may not provide users with enough information about a badge's contents. To make your badge accessible, you must provide a full description with aria-label, as shown in the demo below:

99+

<StyledBadge badgeContent={100}>
  <MailIcon />
</StyledBadge>

<StyledBadge badgeContent={100}>
  <MailIcon />
</StyledBadge>

Press Enter to start editing