diff --git a/docs/components/BadgeDrawable.md b/docs/components/BadgeDrawable.md
index 8392d929ec9..5317dd8b1d0 100644
--- a/docs/components/BadgeDrawable.md
+++ b/docs/components/BadgeDrawable.md
@@ -79,7 +79,7 @@ Option 2: If you do not want `BadgeDrawable` to modify your view hierarchy, you
can specify a `FrameLayout` to display the badge instead.
```java
-* BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
+BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
```
### `BadgeDrawable` Gravity Modes
@@ -90,13 +90,17 @@ of the anchor (with some offsets). Alternatively, you can use `TOP_START` to
align the badge with the top and start edges of the anchor. Note that
`BOTTOM_START` and `BOTTOM_END` are deprecated and not recommended for use.
-### `BadgeDrawable` center offsets
+### `BadgeDrawable` placement and offsets
By default, `BadgeDrawable` is aligned with the top and end edges of its anchor
view (with some offsets if `offsetAlignmentMode` is `legacy`). Call `setBadgeGravity(int)` to change it to one of the
other supported modes. To adjust the badge's offsets relative to the anchor's
center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
+Regardless of offsets, badges are automatically moved to within the bounds of
+its first ancestor view that does not clip its children, to ensure that the
+badge is not clipped if there is enough space.
+
### `BadgeDrawable` Attributes
| Feature | Relevant attributes |
@@ -114,7 +118,6 @@ center, use `setHorizontalOffset(int)` or `setVerticalOffset(int)`
| Horizontal Padding | `app:badgeWidePadding` |
| Vertical Padding | `app:badgeVerticalPadding` |
| Large Font Vertical Offset| `app:largeFontVerticalOffsetAdjustment` |
-| Auto Adjust | `app:autoAdjustToWithinGrandparentBounds` |
**Note:** If both `app:badgeText` and `app:number` are specified, the badge label will be `app:badgeText`.
diff --git a/lib/java/com/google/android/material/badge/BadgeDrawable.java b/lib/java/com/google/android/material/badge/BadgeDrawable.java
index f1700e13275..544e93de5af 100644
--- a/lib/java/com/google/android/material/badge/BadgeDrawable.java
+++ b/lib/java/com/google/android/material/badge/BadgeDrawable.java
@@ -1078,12 +1078,15 @@ int getAdditionalVerticalOffset() {
}
/**
- * Sets whether or not to auto adjust the badge placement to within the badge anchor's
- * grandparent view.
+ * Sets whether or not to auto adjust the badge placement to within the badge anchor's grandparent
+ * view.
*
- * @param autoAdjustToWithinGrandparentBounds whether or not to auto adjust to within
- * the anchor's grandparent view.
+ * @param autoAdjustToWithinGrandparentBounds whether or not to auto adjust to within the anchor's
+ * grandparent view.
+ * @deprecated Badges now automatically adjust their bounds within the first ancestor view that *
+ * clips its children.
*/
+ @Deprecated
public void setAutoAdjustToWithinGrandparentBounds(boolean autoAdjustToWithinGrandparentBounds) {
if (state.isAutoAdjustedToGrandparentBounds() == autoAdjustToWithinGrandparentBounds) {
return;
diff --git a/lib/java/com/google/android/material/badge/BadgeState.java b/lib/java/com/google/android/material/badge/BadgeState.java
index 04e834be546..0ee2a575bc0 100644
--- a/lib/java/com/google/android/material/badge/BadgeState.java
+++ b/lib/java/com/google/android/material/badge/BadgeState.java
@@ -604,10 +604,14 @@ void setNumberLocale(Locale locale) {
currentState.numberLocale = locale;
}
+ /** Deprecated; badges now adjust to within bounds of first ancestor that clips its children */
+ @Deprecated
boolean isAutoAdjustedToGrandparentBounds() {
return currentState.autoAdjustToWithinGrandparentBounds;
}
+ /** Deprecated; badges now adjust to within bounds of first ancestor that clips its children */
+ @Deprecated
void setAutoAdjustToGrandparentBounds(boolean autoAdjustToGrandparentBounds) {
overridingState.autoAdjustToWithinGrandparentBounds = autoAdjustToGrandparentBounds;
currentState.autoAdjustToWithinGrandparentBounds = autoAdjustToGrandparentBounds;
diff --git a/lib/java/com/google/android/material/badge/res-public/values/public.xml b/lib/java/com/google/android/material/badge/res-public/values/public.xml
index b8c6c118160..44268ad3399 100644
--- a/lib/java/com/google/android/material/badge/res-public/values/public.xml
+++ b/lib/java/com/google/android/material/badge/res-public/values/public.xml
@@ -37,6 +37,8 @@
+
diff --git a/lib/java/com/google/android/material/badge/res/values/attrs.xml b/lib/java/com/google/android/material/badge/res/values/attrs.xml
index e2bd0df2e64..022c39693a3 100644
--- a/lib/java/com/google/android/material/badge/res/values/attrs.xml
+++ b/lib/java/com/google/android/material/badge/res/values/attrs.xml
@@ -98,7 +98,8 @@
attribute determines how much to shift the normal vertical offset by. -->
+ grandparent's bounds. Deprecated, badges are now automatically moved to
+ within the first ancestor that clips its children. -->