133 lines
4.3 KiB
Markdown
133 lines
4.3 KiB
Markdown
|
---
|
|||
|
|
productId: joy-ui
|
|||
|
|
title: React Badge component
|
|||
|
|
components: Badge
|
|||
|
|
githubLabel: 'scope: badge'
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Badge
|
|||
|
|
|
|||
|
|
<p class="description">The Badge component generates a small label that is attached to its child element.</p>
|
|||
|
|
|
|||
|
|
{{"component": "@mui/docs/ComponentLinkHeader"}}
|
|||
|
|
|
|||
|
|
## 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.
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeUsage.js", "hideToolbar": true, "bg": "gradient"}}
|
|||
|
|
|
|||
|
|
## Basics
|
|||
|
|
|
|||
|
|
```jsx
|
|||
|
|
import Badge from '@mui/joy/Badge';
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The Badge component wraps around the UI element that it's attached to.
|
|||
|
|
Its default appearance is a dot in the app's `primary` color that sits on the top-right corner of the element that it's attached to.
|
|||
|
|
|
|||
|
|
{{"demo": "SimpleBadge.js"}}
|
|||
|
|
|
|||
|
|
### Content
|
|||
|
|
|
|||
|
|
Use a string or a number as a value for the `badgeContent` prop to display content inside the Badge.
|
|||
|
|
|
|||
|
|
{{"demo": "ContentBadge.js"}}
|
|||
|
|
|
|||
|
|
### Numbers
|
|||
|
|
|
|||
|
|
The following props are useful when `badgeContent` is a number.
|
|||
|
|
|
|||
|
|
#### showZero
|
|||
|
|
|
|||
|
|
By default, the Badge will be automatically hidden when `badgeContent={0}`.
|
|||
|
|
You can override this behavior with the `showZero` prop:
|
|||
|
|
|
|||
|
|
{{"demo": "NumberBadge.js"}}
|
|||
|
|
|
|||
|
|
#### Maximum value
|
|||
|
|
|
|||
|
|
Use the `max` prop to cap the content to a maximum numerical value.
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeMax.js"}}
|
|||
|
|
|
|||
|
|
## Customization
|
|||
|
|
|
|||
|
|
### Variants
|
|||
|
|
|
|||
|
|
The Badge component supports Joy UI's four [global variants](/joy-ui/main-features/global-variants/): `solid` (default), `soft` , `outlined`, and `plain`.
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeVariants.js"}}
|
|||
|
|
|
|||
|
|
:::info
|
|||
|
|
To learn how to add your own variants, check out [Themed components—Extend variants](/joy-ui/customization/themed-components/#extend-variants).
|
|||
|
|
Note that you lose the global variants when you add custom variants.
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
### Sizes
|
|||
|
|
|
|||
|
|
The Badge component comes in three sizes: `sm`, `md` (default), and `lg`:
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeSizes.js"}}
|
|||
|
|
|
|||
|
|
:::info
|
|||
|
|
To learn how to add custom sizes to the component, check out [Themed components—Extend sizes](/joy-ui/customization/themed-components/#extend-sizes).
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
### Colors
|
|||
|
|
|
|||
|
|
Every palette included in the theme is available via the `color` prop.
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeColors.js"}}
|
|||
|
|
|
|||
|
|
### Visibility
|
|||
|
|
|
|||
|
|
Use the `invisible` prop to control the Badge's visibility.
|
|||
|
|
|
|||
|
|
:::warning
|
|||
|
|
If [`showZero`](#numbers) and `invisible` are both applied at the same time, then the Badge will still be visible when `badgeContent={0}`.
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeVisibility.js"}}
|
|||
|
|
|
|||
|
|
### Position
|
|||
|
|
|
|||
|
|
By default, the Badge sits on the top-right corner of the element that it's attached to.
|
|||
|
|
Use the `anchorOrigin` prop to change the position of the Badge according to its `vertical` (top or bottom) and `horizontal` (left or right) placement.
|
|||
|
|
Try clicking the arrows in the demo below to change the position of the Badge:
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeAlignment.js", "hideToolbar": true}}
|
|||
|
|
|
|||
|
|
### Inset
|
|||
|
|
|
|||
|
|
Use the `badgeInset` prop to fine-tune the position of the Badge relative to the element that it's attached to.
|
|||
|
|
This prop accepts a string composed of numbers expressed in units of `px`, `%`, `em`, or `rem`. (This syntax corresponds to the [inset CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/inset).)
|
|||
|
|
|
|||
|
|
This string defines the inset from the Badge's [`anchorOrigin`](#position)—for instance, the demo below pushes the Badge 14% closer to the center of its child element (relative to the top-right corner) along both the vertical and horizontal axes:
|
|||
|
|
|
|||
|
|
{{"demo": "BadgeInset.js"}}
|
|||
|
|
|
|||
|
|
If you pass two unit-numbers to the `badgeInset` prop—for example`"50px 10px"`—the first number applies to the vertical axis, and the second applies horizontally.
|
|||
|
|
If you pass four unit-numbers to the prop—such as `"0 -10px 0 5px"`, they are applied clockwise starting from the top.
|
|||
|
|
|
|||
|
|
## 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:
|
|||
|
|
|
|||
|
|
{{"demo": "AccessibleBadges.js"}}
|
|||
|
|
|
|||
|
|
## Anatomy
|
|||
|
|
|
|||
|
|
The Badge component is composed of a root `<span>` that houses the element that the Badge is attached to, followed by a `<span>` to represent the Badge itself:
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<span class="MuiBadge-root">
|
|||
|
|
<!-- the element the Badge is attached to -->
|
|||
|
|
<span class="MuiBadge-badge">
|
|||
|
|
<!-- Badge content -->
|
|||
|
|
</span>
|
|||
|
|
</span>
|
|||
|
|
```
|