Badge generates a small badge to the top-right of its child(ren).
+Badge displays small status or count information aligned to its wrapped element.
{{"component": "@mui/docs/ComponentLinkHeader"}} +> For full API and props, see [Badge API](/material-ui/api/badge/). + ## Basic badge Examples of badges containing text, using primary and secondary colors. The badge is applied to its children. {{"demo": "SimpleBadge.js"}} +Use badges for lightweight status or counts. Avoid relying on the badge text alone to convey meaning. + ## Color Use `color` prop to apply theme palette to component. {{"demo": "ColorBadge.js"}} +Pick colors that reflect semantic meaning (e.g., success/error/info) and ensure sufficient contrast. + ## Customization Here is an example of customizing the component. @@ -31,6 +37,8 @@ You can learn more about this in the [overrides documentation page](/material-ui {{"demo": "CustomizedBadges.js"}} +Target the badge element via `& .MuiBadge-badge` in `sx` or theme overrides to fine-tune size, color, and offsets. + ## Badge visibility The visibility of badges can be controlled using the `invisible` prop. @@ -39,6 +47,8 @@ The visibility of badges can be controlled using the `invisible` prop. The badge hides automatically when `badgeContent` is zero. You can override this with the `showZero` prop. +If “0” is meaningful in your UI (e.g., explicit emptiness), enable `showZero` so users aren’t confused. + {{"demo": "ShowZeroBadge.js"}} ## Maximum value @@ -47,27 +57,51 @@ You can use the `max` prop to cap the value of the badge content. {{"demo": "BadgeMax.js"}} +Cap large counts with `max` (e.g., 99+) to reduce cognitive load and avoid layout shifts. + ## Dot badge The `dot` prop changes a badge into a small dot. This can be used as a notification that something has changed without giving a count. {{"demo": "DotBadge.js"}} +The `dot` variant signals attention without a number; pair it with descriptive text for assistive technologies. + ## Badge overlap You can use the `overlap` prop to place the badge relative to the corner of the wrapped element. {{"demo": "BadgeOverlap.js"}} +Use `overlap="circular"` for round children (e.g., `Avatar`) and `overlap="rectangular"` for square/rectangular ones. + ## Badge alignment You can use the `anchorOrigin` prop to move the badge to any corner of the wrapped element. {{"demo": "BadgeAlignment.js", "hideToolbar": true}} +Verify alignment visually when using non-standard child sizes (icons 20/24/28px may need different `anchorOrigin`). + +## Best practices + +- showZero: Enable when zero carries meaning (e.g., empty state clarity). +- max: Prefer compact display (e.g., 99+) to reduce cognitive load. +- Semantics: Badge supplements content; don’t rely on it as the only indicator. + +## Composition tips + +- With `IconButton` and `Avatar`, pick `overlap` that matches the child shape. +- Space multiple badges using `Stack` and `gap` to prevent visual crowding. + +## Theming and customization + +Customize the badge appearance via `sx` or theme overrides: +- Target the badge element with `& .MuiBadge-badge` for size, color, and offset tweaks. +- Align offsets to the child’s actual size (icons 20/24/28px may need different `anchorOrigin`). + ## Accessibility -You can't rely on the content of the badge to be announced correctly. -You should provide a full description, for instance, with `aria-label`: +Screen readers may not announce `badgeContent` reliably. Provide a full description on the focusable parent, for instance with `aria-label` (e.g., `aria-label="3 unread notifications"`). For `variant="dot"`, always include a complementary text description. {{"demo": "AccessibleBadges.js"}} diff --git a/docs/data/material/components/cards/cards.md b/docs/data/material/components/cards/cards.md index 2eddaaf0688aa2..a41f67f15cf041 100644 --- a/docs/data/material/components/cards/cards.md +++ b/docs/data/material/components/cards/cards.md @@ -12,18 +12,19 @@ githubSource: packages/mui-material/src/CardCards contain content and actions about a single subject.
{{"component": "@mui/docs/ComponentLinkHeader"}} +> For full API and props, see [Card API](/material-ui/api/card/). ## Introduction Cards are surfaces that display content and actions on a single topic. -The Material UI Card component includes several complementary utility components to handle various use cases: +The MUI Card component includes several complementary utility components to handle various use cases: -- Card: a surface-level container for grouping related components. -- Card Content: the wrapper for the Card content. -- Card Header: an optional wrapper for the Card header. -- Card Media: an optional container for displaying images, videos, etc. -- Card Actions: an optional wrapper that groups a set of buttons. -- Card Action Area: an optional wrapper that allows users to interact with the specified area of the Card. +- Card: a container for grouping related content and actions. +- CardContent: the wrapper for the card’s main content. +- CardHeader: an optional wrapper for the card’s header area. +- CardMedia: an optional container for images, videos, and other media. +- CardActions: an optional wrapper that groups action buttons. +- CardActionArea: an optional wrapper that makes a defined area of the card interactive. {{"demo": "BasicCard.js", "bg": true}} @@ -58,15 +59,17 @@ Example of a card using an image to reinforce the content. By default, we use the combination of a `