Skip to content

Commit a1e2f9e

Browse files
Material Design Teamhunterstich
Material Design Team
authored and
hunterstich
committed
[Docs] Updated Badges doc to make it more user friendly
PiperOrigin-RevId: 772821066
1 parent 6b41a60 commit a1e2f9e

File tree

5 files changed

+76
-44
lines changed

5 files changed

+76
-44
lines changed

‎docs/components/BadgeDrawable.md‎

Lines changed: 76 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,31 @@
11
<!--docs:
2-
title: "Badge"
2+
title: "Badges"
33
layout: detail
44
section: components
55
excerpt: "Badges can contain dynamic information, such as a number of pending requests."
66
iconId: badge
77
path: /catalog/badging/
88
-->
99

10-
# `BadgeDrawable`
10+
# Badges
1111

12-
## Design and API Documentation
12+
[Badges](https://m3.material.io/components/badges/overview) show notifications,
13+
counts, or status information on navigation items and icons. There are two
14+
variants of badges.
1315

14-
* [Google Material3 Spec](https://material.io/components/badges/overview)
15-
* [API reference](https://developer.android.com/reference/com/google/android/material/badge/package-summary)
16+
<img src="assets/badge/small_badge_hero.png" alt="Small badge" height="250"/> | <img src="assets/badge/large_badge_hero.png" alt="Large badge" height="250"/>
17+
----------------------------------------------------------------------------- | -----------------------------------------------------------------------------
18+
1 | 2
19+
20+
1. Small badge
21+
2. Large badge
1622

17-
## Using badges
23+
**Note:** Images use various dynamic color schemes.
1824

19-
Badge | Badge with number | Badge with a maximum character count
20-
--------------------------------------------- | ---------------------------------------------------- | ------------------------------------
21-
![badge_icon](assets/badge/IconOnlyBadge.png) | ![badge_with_number_99](assets/badge/BadgeNumber.png) | ![badge_with_999+](assets/badge/BadgeNumberLongerThanMaxCharCount.png)
25+
Before you can use Material badges, you need to add a dependency to the Material
26+
components for Android library. For more information, go to the
27+
[Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
28+
page.
2229

2330
**Note:** This component is still under development and may not support the full
2431
range of customization Material Android components generally support, for
@@ -28,7 +35,53 @@ A `BadgeDrawable` represents dynamic information such as a number of pending
2835
requests in a [`BottomNavigationView`](BottomNavigation.md) or
2936
[`TabLayout`](Tabs.md).
3037

31-
## Usage
38+
## Design & API documentation
39+
40+
* [Material 3 (M3) spec](https://m3.material.io/components/badges/overview)
41+
* [API reference](https://developer.android.com/reference/com/google/android/material/badge/package-summary)
42+
43+
## Anatomy
44+
45+
<img src="assets/badge/badges_anatomy.png" alt="Small and large badges anatomy" width="800"/>
46+
47+
1. Small badge
48+
2. Large badge container
49+
3. Large badge label
50+
51+
More details on anatomy items in the
52+
[component guidelines](https://m3.material.io/components/badges/guidelines#07608fcc-43f7-47b3-b5cb-ee617753b877).
53+
54+
## Key properties
55+
56+
### `BadgeDrawable` Attributes
57+
58+
| Feature | Relevant attributes |
59+
|----------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------|
60+
| Color | `app:backgroundColor` <br> `app:badgeTextColor` |
61+
| Width | `app:badgeWidth` <br> `app:badgeWithTextWidth` |
62+
| Height | `app:badgeHeight` <br> `app:badgeWithTextHeight` |
63+
| Shape | `app:badgeShapeAppearance` <br> `app:badgeShapeAppearanceOverlay` <br> `app:badgeWithTextShapeAppearance` <br> `app:badgeWithTextShapeAppearanceOverlay` |
64+
| Label | `app:badgeText` (for text) <br> `app:number` (for numbers) |
65+
| Label Length | `app:maxCharacterCount` (for all text) <br> `app:maxNumber` (for numbers only) |
66+
| Label Text Color | `app:badgeTextColor` |
67+
| Label Text Appearance | `app:badgeTextAppearance` |
68+
| Badge Gravity | `app:badgeGravity` |
69+
| Offset Alignment | `app:offsetAlignmentMode` |
70+
| Horizontal Padding | `app:badgeWidePadding` |
71+
| Vertical Padding | `app:badgeVerticalPadding` |
72+
| Large Font Vertical Offset| `app:largeFontVerticalOffsetAdjustment` |
73+
| Badge Fixed Edge | `app:badgeFixedEdge` |
74+
75+
**Note:** If both `app:badgeText` and `app:number` are specified, the badge
76+
label will be `app:badgeText`.
77+
78+
## Code implementation
79+
80+
![Two variants of badges](assets/badge/badges_hero.png)
81+
82+
1. Small badge on a navigation item
83+
2. Large badge on a navigation item
84+
3. Large badge with max characters on a navigation item
3285

3386
API and source code:
3487

@@ -82,7 +135,7 @@ can specify a `FrameLayout` to display the badge instead.
82135
BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
83136
```
84137

85-
### `BadgeDrawable` Gravity Modes
138+
### `BadgeDrawable` gravity modes
86139

87140
`BadgeDrawable` offers two gravity modes to control how the badge aligns with
88141
its anchor view. By default, (`TOP_END`) badge aligns with the top and end edges
@@ -93,42 +146,21 @@ align the badge with the top and start edges of the anchor. Note that
93146
### `BadgeDrawable` placement and offsets
94147

95148
By default, `BadgeDrawable` is aligned with the top and end edges of its anchor
96-
view (with some offsets if `offsetAlignmentMode` is `legacy`). Call `setBadgeGravity(int)` to change it to one of the
97-
other supported modes. To adjust the badge's offsets relative to the anchor's
98-
center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
149+
view (with some offsets if `offsetAlignmentMode` is `legacy`). Call
150+
`setBadgeGravity(int)` to change it to one of the other supported modes. To
151+
adjust the badge's offsets relative to the anchor's center, use
152+
`setHorizontalOffset(int)` or `setVerticalOffset(int)`
99153

100154
Regardless of offsets, badges are automatically moved to within the bounds of
101155
its first ancestor view that does not clip its children, to ensure that the
102156
badge is not clipped if there is enough space.
103157

104-
### `BadgeDrawable` Attributes
105-
106-
| Feature | Relevant attributes |
107-
|----------------------- |----------------------------------------------------------------------------------------------------------------------------------------------------------|
108-
| Color | `app:backgroundColor` <br> `app:badgeTextColor` |
109-
| Width | `app:badgeWidth` <br> `app:badgeWithTextWidth` |
110-
| Height | `app:badgeHeight` <br> `app:badgeWithTextHeight` |
111-
| Shape | `app:badgeShapeAppearance` <br> `app:badgeShapeAppearanceOverlay` <br> `app:badgeWithTextShapeAppearance` <br> `app:badgeWithTextShapeAppearanceOverlay` |
112-
| Label | `app:badgeText` (for text) <br> `app:number` (for numbers) |
113-
| Label Length | `app:maxCharacterCount` (for all text) <br> `app:maxNumber` (for numbers only) |
114-
| Label Text Color | `app:badgeTextColor` |
115-
| Label Text Appearance | `app:badgeTextAppearance` |
116-
| Badge Gravity | `app:badgeGravity` |
117-
| Offset Alignment | `app:offsetAlignmentMode` |
118-
| Horizontal Padding | `app:badgeWidePadding` |
119-
| Vertical Padding | `app:badgeVerticalPadding` |
120-
| Large Font Vertical Offset| `app:largeFontVerticalOffsetAdjustment` |
121-
| Badge Fixed Edge | `app:badgeFixedEdge` |
122-
123-
124-
**Note:** If both `app:badgeText` and `app:number` are specified, the badge label will be `app:badgeText`.
125-
126-
### Talkback Support
158+
### TalkBack support
127159

128-
`BadgeDrawable` provides a getter for its content description, which is based on the displayed
129-
number or text (if any). To specify the content description, the developer is provided
130-
with the following methods:
131-
- `setContentDescriptionForText(CharSequence)`
132-
- `setContentDescriptionQuantityStringsResource(@PluralsRes int)`
133-
- `setContentDescriptionExceedsMaxBadgeNumberStringResource(@StringRes int)`
134-
- `setContentDescriptionNumberless(CharSequence)`
160+
`BadgeDrawable` provides a getter for its content description, which is based on
161+
the displayed number or text (if any). To specify the content description, the
162+
developer is provided with the following methods:
163+
`setContentDescriptionForText(CharSequence)`
164+
`setContentDescriptionQuantityStringsResource(@PluralsRes int)`
165+
`setContentDescriptionExceedsMaxBadgeNumberStringResource(@StringRes int)`
166+
`setContentDescriptionNumberless(CharSequence)`

‎docs/components/assets/badge/badges_anatomy.png‎

18.2 KB
Loading

‎docs/components/assets/badge/badges_hero.png‎

14.5 KB
Loading

‎docs/components/assets/badge/large_badge_hero.png‎

11 KB
Loading

‎docs/components/assets/badge/small_badge_hero.png‎

10.3 KB
Loading

0 commit comments

Comments
 (0)