BadgeDrawable

public class BadgeDrawable
extends Drawable

java.lang.Object
   ↳ android.graphics.drawable.Drawable
     ↳ com.google.android.material.badge.BadgeDrawable


BadgeDrawable contains all the layout and draw logic for a badge.

You can use BadgeDrawable to display dynamic information such as a number of pending requests in a BottomNavigationView. To create an instance of BadgeDrawable, use create(Context) or createFromResource(Context, int). How to add and display a BadgeDrawable on top of its anchor view depends on the API level:

For API 18+ (APIs supported by ViewOverlay)

  • Add BadgeDrawable as a ViewOverlay to the desired anchor view using BadgeUtils#attachBadgeDrawable(BadgeDrawable, View, FrameLayout) (This helper class is currently experimental).
  • Update the BadgeDrawable BadgeDrawable's coordinates (center and bounds) based on its anchor view using updateBadgeCoordinates(View, FrameLayout).
 BadgeDrawable badgeDrawable = BadgeDrawable.create(context);
 badgeDrawable.setVisible(true);
 BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor);
 

For Pre API-18

Option 1: BadgeDrawable will dynamically create and wrap the anchor view in a FrameLayout, then insert the FrameLayout into the anchor view original position in the view hierarchy. Same syntax as API 18+
 BadgeDrawable badgeDrawable = BadgeDrawable.create(context);
 badgeDrawable.setVisible(true);
 BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor);
 
Option 2: If you do not want BadgeDrawable to modify your view hierarchy, you can specify a FrameLayout to display the badge instead.
 BadgeDrawable badgeDrawable = BadgeDrawable.create(context);
 BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor, anchorFrameLayoutParent);
 

By default, BadgeDrawable is aligned to the top and end edges of its anchor view (with some offsets). Call setBadgeGravity(int) to change it to TOP_START, the other supported mode. To adjust the badge's offsets w.r.t. the anchor's center, use setHorizontalOffset(int), setVerticalOffset(int)

Note: This is still under development and may not support the full range of customization Material Android components generally support (e.g. themed attributes).

For more information, see the component developer guidance and design guidelines.

Summary

Nested classes

@interface BadgeDrawable.BadgeGravity

Position the badge can be set to. 

XML attributes

Badge_backgroundColor  
Badge_badgeShapeAppearance  
Badge_badgeShapeAppearanceOverlay  
Badge_badgeText  
Badge_badgeTextAppearance  
Badge_badgeTextColor  
Badge_badgeVerticalPadding  
Badge_badgeWidePadding  
Badge_badgeWithTextShapeAppearance  
Badge_badgeWithTextShapeAppearanceOverlay  
Badge_maxCharacterCount  
Badge_maxNumber  
Badge_number  

Constants

int BADGE_CONTENT_NOT_TRUNCATED

A value to indicate that badge content should not be truncated.

int BOTTOM_END

This constant is deprecated. Bottom badge gravities are deprecated in favor of top gravities; use TOP_START or TOP_END instead.

int BOTTOM_START

This constant is deprecated. Bottom badge gravities are deprecated in favor of top gravities; use TOP_START or TOP_END instead.

int TOP_END

The badge is positioned along the top and end edges of its anchor view

int TOP_START

The badge is positioned along the top and start edges of its anchor view

Public methods

void clearNumber()

Clears the badge's number.

void clearText()

Clears the badge's text.

static BadgeDrawable create(Context context)

Creates an instance of BadgeDrawable with default values.

static BadgeDrawable createFromResource(Context context, int id)

Returns a BadgeDrawable from the given XML resource.

void draw(Canvas canvas)
int getAlpha()
int getBackgroundColor()

Returns this badge's background color.

int getBadgeGravity()
Locale getBadgeNumberLocale()

Returns the Locale used to show badge numbers.

int getBadgeTextColor()

Returns this badge's text color.

CharSequence getContentDescription()
FrameLayout getCustomBadgeParent()

Returns a FrameLayout that will set this BadgeDrawable as its foreground.

int getHorizontalOffset()

Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor.

int getHorizontalOffsetWithText()

Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge has text.

int getHorizontalOffsetWithoutText()

Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge does not have text (is a dot).

int getHorizontalPadding()

Returns the badge horizontal padding in pixels.

int getIntrinsicHeight()

Returns the height at which the badge would like to be laid out.

int getIntrinsicWidth()

Returns the width at which the badge would like to be laid out.

int getLargeFontVerticalOffsetAdjustment()

Returns how much (in pixels) this badge is being vertically moved away the center of its anchor when the badge has text and the font scale is at max.

int getMaxCharacterCount()

Returns this badge's max character count.

int getMaxNumber()

Returns this badge's max number.

int getNumber()

Returns the badge's number.

int getOpacity()
String getText()

Returns the badge's text.

int getVerticalOffset()

Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor.

int getVerticalOffsetWithText()

Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor when the badge has text.

int getVerticalOffsetWithoutText()

Returns how much (in pixels) this badge is being vertically offset towards the center of its anchor when this badge does not have text (is a dot).

int getVerticalPadding()

Returns the badge vertical padding in pixels.

boolean hasNumber()

Returns whether this badge will display a number.

boolean hasText()

Returns whether the badge will display a text.

boolean isStateful()
boolean onStateChange(int[] state)
void setAlpha(int alpha)
void setAutoAdjustToWithinGrandparentBounds(boolean autoAdjustToWithinGrandparentBounds)

Sets whether or not to auto adjust the badge placement to within the badge anchor's grandparent view.

void setBackgroundColor(int backgroundColor)

Sets this badge's background color.

void setBadgeGravity(int gravity)

Sets this badge's gravity with respect to its anchor view.

void setBadgeNumberLocale(Locale locale)

Sets the Locale used to show badge numbers.

void setBadgeTextColor(int badgeTextColor)

Sets this badge's text color.

void setBadgeWithTextShapeAppearance(int id)

Sets this badge with text's shape appearance resource.

void setBadgeWithTextShapeAppearanceOverlay(int id)

Sets this badge with text's shape appearance overlay resource.

void setBadgeWithoutTextShapeAppearance(int id)

Sets this badge without text's shape appearance resource.

void setBadgeWithoutTextShapeAppearanceOverlay(int id)

Sets this badge without text's shape appearance overlay resource.

void setColorFilter(ColorFilter colorFilter)
void setContentDescriptionExceedsMaxBadgeNumberStringResource(int stringsResource)

Specifies the content description if the badge number exceeds the maximum value.

void setContentDescriptionForText(CharSequence charSequence)

Specifies the content description if the text is set for the badge.

void setContentDescriptionNumberless(CharSequence charSequence)

Specifies the content description if no text or number is set for the badge.

void setContentDescriptionQuantityStringsResource(int stringsResource)

Specifies the content description if the number is set for the badge.

void setHorizontalOffset(int px)

Sets how much (in pixels) to horizontally move this badge towards the center of its anchor.

void setHorizontalOffsetWithText(int px)

Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge has text.

void setHorizontalOffsetWithoutText(int px)

Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge does not have text (is a dot).

void setHorizontalPadding(int horizontalPadding)

Sets how much (in pixels) horizontal padding to add to the badge when it has label contents.

void setLargeFontVerticalOffsetAdjustment(int px)

Sets how much (in pixels) to vertically move this badge away the center of its anchor when this badge has text and the font scale is at max size.

void setMaxCharacterCount(int maxCharacterCount)

Sets this badge's max character count.

void setMaxNumber(int maxNumber)

Sets this badge's max number.

void setNumber(int number)

Sets the badge's number.

void setText(String text)

Sets the badge's text.

void setTextAppearance(int id)

Sets this badge's text appearance resource.

void setVerticalOffset(int px)

Sets how much (in pixels) to vertically move this badge towards the center of its anchor.

void setVerticalOffsetWithText(int px)

Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge has text.

void setVerticalOffsetWithoutText(int px)

Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge does not have text (is a dot).

void setVerticalPadding(int verticalPadding)

Sets how much (in pixels) vertical padding to add to the badge when it has label contents.

void setVisible(boolean visible)

Convenience wrapper method for Drawable.setVisible(boolean, boolean) with the restart parameter hardcoded to false.

void updateBadgeCoordinates(View anchorView, ViewGroup customBadgeParent)

This method is deprecated. use updateBadgeCoordinates(View, FrameLayout) instead.

void updateBadgeCoordinates(View anchorView, FrameLayout customBadgeParent)

Calculates and updates this badge's center coordinates based on its anchor's bounds.

void updateBadgeCoordinates(View anchorView)

Calculates and updates this badge's center coordinates based on its anchor's bounds.

Inherited methods

XML attributes

Badge_backgroundColor

Related methods:

Badge_badgeShapeAppearance

Related methods:

Badge_badgeShapeAppearanceOverlay

Related methods:

Badge_badgeText

Related methods:

Badge_badgeTextAppearance

Related methods:

Badge_badgeTextColor

Related methods:

Badge_badgeVerticalPadding

Related methods:

Badge_badgeWidePadding

Related methods:

Badge_badgeWithTextShapeAppearance

Related methods:

Badge_badgeWithTextShapeAppearanceOverlay

Related methods:

Badge_maxCharacterCount

Related methods:

Badge_maxNumber

Related methods:

Badge_number

Related methods:

Constants

BADGE_CONTENT_NOT_TRUNCATED

public static final int BADGE_CONTENT_NOT_TRUNCATED

A value to indicate that badge content should not be truncated.

Constant Value: -2 (0xfffffffe)

BOTTOM_END

public static final int BOTTOM_END

This constant is deprecated.
Bottom badge gravities are deprecated in favor of top gravities; use TOP_START or TOP_END instead.

The badge is positioned along the bottom and end edges of its anchor view

Constant Value: 8388693 (0x00800055)

BOTTOM_START

public static final int BOTTOM_START

This constant is deprecated.
Bottom badge gravities are deprecated in favor of top gravities; use TOP_START or TOP_END instead.

The badge is positioned along the bottom and start edges of its anchor view

Constant Value: 8388691 (0x00800053)

TOP_END

public static final int TOP_END

The badge is positioned along the top and end edges of its anchor view

Constant Value: 8388661 (0x00800035)

TOP_START

public static final int TOP_START

The badge is positioned along the top and start edges of its anchor view

Constant Value: 8388659 (0x00800033)

Public methods

clearNumber

public void clearNumber ()

Clears the badge's number.

clearText

public void clearText ()

Clears the badge's text.

create

public static BadgeDrawable create (Context context)

Creates an instance of BadgeDrawable with default values.

Parameters
context Context

Returns
BadgeDrawable

createFromResource

public static BadgeDrawable createFromResource (Context context, 
                int id)

Returns a BadgeDrawable from the given XML resource. All attributes from R.styleable.Badge and a custom style attribute are supported. A badge resource may look like:

<badge
     xmlns:app="http://schemas.android.com/apk/res-auto"
     style="@style/Widget.MaterialComponents.Badge"
     app:maxCharacterCount="2"/>
 

Parameters
context Context

id int

Returns
BadgeDrawable

draw

public void draw (Canvas canvas)

Parameters
canvas Canvas

getAlpha

public int getAlpha ()

Returns
int

getBackgroundColor

public int getBackgroundColor ()

Returns this badge's background color.

Related XML Attributes:

Returns
int

getBadgeGravity

public int getBadgeGravity ()

Returns
int

getBadgeNumberLocale

public Locale getBadgeNumberLocale ()

Returns the Locale used to show badge numbers.

Returns
Locale

getBadgeTextColor

public int getBadgeTextColor ()

Returns this badge's text color.

Related XML Attributes:

Returns
int

getContentDescription

public CharSequence getContentDescription ()

Returns
CharSequence

getCustomBadgeParent

public FrameLayout getCustomBadgeParent ()

Returns a FrameLayout that will set this BadgeDrawable as its foreground.

Returns
FrameLayout

getHorizontalOffset

public int getHorizontalOffset ()

Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor.

This returns the horizontal offset for badges without text. If offset for badges with text and without text are different consider using getHorizontalOffsetWithoutText() or getHorizontalOffsetWithText().

Returns
int

getHorizontalOffsetWithText

public int getHorizontalOffsetWithText ()

Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge has text.

Returns
int

getHorizontalOffsetWithoutText

public int getHorizontalOffsetWithoutText ()

Returns how much (in pixels) this badge is being horizontally offset towards the center of its anchor when this badge does not have text (is a dot).

Returns
int

getHorizontalPadding

public int getHorizontalPadding ()

Returns the badge horizontal padding in pixels.

Returns
int

getIntrinsicHeight

public int getIntrinsicHeight ()

Returns the height at which the badge would like to be laid out.

Returns
int

getIntrinsicWidth

public int getIntrinsicWidth ()

Returns the width at which the badge would like to be laid out.

Returns
int

getLargeFontVerticalOffsetAdjustment

public int getLargeFontVerticalOffsetAdjustment ()

Returns how much (in pixels) this badge is being vertically moved away the center of its anchor when the badge has text and the font scale is at max. Note that this is not the total vertical offset.

Returns
int

getMaxCharacterCount

public int getMaxCharacterCount ()

Returns this badge's max character count.

Related XML Attributes:

Returns
int

getMaxNumber

public int getMaxNumber ()

Returns this badge's max number. If maxCharacterCount is set, it will override this number.

Related XML Attributes:

Returns
int

See also:

getNumber

public int getNumber ()

Returns the badge's number. Only non-negative integer numbers will be returned because the setter clamps negative values to 0.

WARNING: Do not call this method if you are planning to compare to BADGE_NUMBER_NONE

Related XML Attributes:

Returns
int

See also:

getOpacity

public int getOpacity ()

Returns
int

getText

public String getText ()

Returns the badge's text.

Related XML Attributes:

Returns
String

See also:

getVerticalOffset

public int getVerticalOffset ()

Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor.

This returns the vertical offset for badges without text. If offset for badges with text and without text are different consider using getVerticalOffsetWithoutText() or getVerticalOffsetWithText().

Returns
int

getVerticalOffsetWithText

public int getVerticalOffsetWithText ()

Returns how much (in pixels) this badge is being vertically moved towards the center of its anchor when the badge has text.

Returns
int

getVerticalOffsetWithoutText

public int getVerticalOffsetWithoutText ()

Returns how much (in pixels) this badge is being vertically offset towards the center of its anchor when this badge does not have text (is a dot).

Returns
int

getVerticalPadding

public int getVerticalPadding ()

Returns the badge vertical padding in pixels.

Returns
int

hasNumber

public boolean hasNumber ()

Returns whether this badge will display a number.

Returns
boolean

hasText

public boolean hasText ()

Returns whether the badge will display a text.

Returns
boolean

isStateful

public boolean isStateful ()

Returns
boolean

onStateChange

public boolean onStateChange (int[] state)

Parameters
state int

Returns
boolean

setAlpha

public void setAlpha (int alpha)

Parameters
alpha int

setAutoAdjustToWithinGrandparentBounds

public void setAutoAdjustToWithinGrandparentBounds (boolean autoAdjustToWithinGrandparentBounds)

Sets whether or not to auto adjust the badge placement to within the badge anchor's grandparent view.

Parameters
autoAdjustToWithinGrandparentBounds boolean: whether or not to auto adjust to within the anchor's grandparent view.

setBackgroundColor

public void setBackgroundColor (int backgroundColor)

Sets this badge's background color.

Related XML Attributes:

Parameters
backgroundColor int: This badge's background color.

setBadgeGravity

public void setBadgeGravity (int gravity)

Sets this badge's gravity with respect to its anchor view.

Parameters
gravity int: Constant representing one of the possible BadgeDrawable.BadgeGravity values. There are two recommended gravities: TOP_START and TOP_END.

setBadgeNumberLocale

public void setBadgeNumberLocale (Locale locale)

Sets the Locale used to show badge numbers.

Parameters
locale Locale

setBadgeTextColor

public void setBadgeTextColor (int badgeTextColor)

Sets this badge's text color.

Related XML Attributes:

Parameters
badgeTextColor int: This badge's text color.

setBadgeWithTextShapeAppearance

public void setBadgeWithTextShapeAppearance (int id)

Sets this badge with text's shape appearance resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance res id when there is text.

setBadgeWithTextShapeAppearanceOverlay

public void setBadgeWithTextShapeAppearanceOverlay (int id)

Sets this badge with text's shape appearance overlay resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance overlay res id when there is text.

setBadgeWithoutTextShapeAppearance

public void setBadgeWithoutTextShapeAppearance (int id)

Sets this badge without text's shape appearance resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance res id when there is no text.

setBadgeWithoutTextShapeAppearanceOverlay

public void setBadgeWithoutTextShapeAppearanceOverlay (int id)

Sets this badge without text's shape appearance overlay resource.

Related XML Attributes:

Parameters
id int: This badge's shape appearance overlay res id when there is no text.

setColorFilter

public void setColorFilter (ColorFilter colorFilter)

Parameters
colorFilter ColorFilter

setContentDescriptionExceedsMaxBadgeNumberStringResource

public void setContentDescriptionExceedsMaxBadgeNumberStringResource (int stringsResource)

Specifies the content description if the badge number exceeds the maximum value.

Parameters
stringsResource int

setContentDescriptionForText

public void setContentDescriptionForText (CharSequence charSequence)

Specifies the content description if the text is set for the badge. If the text is set for the badge and the content description is null, the badge text will be used as the content description by default.

Parameters
charSequence CharSequence

setContentDescriptionNumberless

public void setContentDescriptionNumberless (CharSequence charSequence)

Specifies the content description if no text or number is set for the badge.

Parameters
charSequence CharSequence

setContentDescriptionQuantityStringsResource

public void setContentDescriptionQuantityStringsResource (int stringsResource)

Specifies the content description if the number is set for the badge.

Parameters
stringsResource int

setHorizontalOffset

public void setHorizontalOffset (int px)

Sets how much (in pixels) to horizontally move this badge towards the center of its anchor.

This sets the horizontal offset for badges without text (dots) and with text.

Parameters
px int: badge's horizontal offset

setHorizontalOffsetWithText

public void setHorizontalOffsetWithText (int px)

Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge has text.

Parameters
px int: badge's horizontal offset when the badge has text.

setHorizontalOffsetWithoutText

public void setHorizontalOffsetWithoutText (int px)

Sets how much (in pixels) to horizontally move this badge towards the center of its anchor when this badge does not have text (is a dot).

Parameters
px int: badge's horizontal offset when the badge does not have text

setHorizontalPadding

public void setHorizontalPadding (int horizontalPadding)

Sets how much (in pixels) horizontal padding to add to the badge when it has label contents. Note that badges have a minimum width as specified by com.google.android.material.R.styleable#Badge_badgeWidth.

Related XML Attributes:

Parameters
horizontalPadding int: badge's horizontal padding

setLargeFontVerticalOffsetAdjustment

public void setLargeFontVerticalOffsetAdjustment (int px)

Sets how much (in pixels) to vertically move this badge away the center of its anchor when this badge has text and the font scale is at max size. This is in conjunction with the vertical offset with text.

Parameters
px int: how much to move the badge's vertical offset away from the center by when the font is large.

setMaxCharacterCount

public void setMaxCharacterCount (int maxCharacterCount)

Sets this badge's max character count.

Related XML Attributes:

Parameters
maxCharacterCount int: This badge's max character count.

setMaxNumber

public void setMaxNumber (int maxNumber)

Sets this badge's max number. If maxCharacterCount is set, it will override this number.

Related XML Attributes:

Parameters
maxNumber int: This badge's max number.

setNumber

public void setNumber (int number)

Sets the badge's number. Only non-negative integer numbers are supported. If the number is negative, it will be clamped to 0. The specified value will be displayed, unless its number of digits exceeds maxCharacterCount in which case a truncated version will be shown.

Related XML Attributes:

Parameters
number int: This badge's number.

setText

public void setText (String text)

Sets the badge's text. The specified text will be displayed, unless its length exceeds maxCharacterCount in which case a truncated version will be shown.

Related XML Attributes:

Parameters
text String

See also:

setTextAppearance

public void setTextAppearance (int id)

Sets this badge's text appearance resource.

Related XML Attributes:

Parameters
id int: This badge's text appearance res id.

setVerticalOffset

public void setVerticalOffset (int px)

Sets how much (in pixels) to vertically move this badge towards the center of its anchor.

This sets the vertical offset for badges both without text (dots) and with text.

Parameters
px int: badge's vertical offset

setVerticalOffsetWithText

public void setVerticalOffsetWithText (int px)

Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge has text.

Parameters
px int: badge's vertical offset when the badge has text.

setVerticalOffsetWithoutText

public void setVerticalOffsetWithoutText (int px)

Sets how much (in pixels) to vertically move this badge towards the center of its anchor when this badge does not have text (is a dot).

Parameters
px int: badge's vertical offset when the badge does not have text

setVerticalPadding

public void setVerticalPadding (int verticalPadding)

Sets how much (in pixels) vertical padding to add to the badge when it has label contents. Note that badges have a minimum height as specified by com.google.android.material.R.styleable#Badge_badgeHeight.

Related XML Attributes:

Parameters
verticalPadding int: badge's vertical padding

setVisible

public void setVisible (boolean visible)

Convenience wrapper method for Drawable.setVisible(boolean, boolean) with the restart parameter hardcoded to false.

Parameters
visible boolean

updateBadgeCoordinates

public void updateBadgeCoordinates (View anchorView, 
                ViewGroup customBadgeParent)

This method is deprecated.
use updateBadgeCoordinates(View, FrameLayout) instead.

Calculates and updates this badge's center coordinates based on its anchor's bounds. Internally also updates this BadgeDrawable BadgeDrawable's bounds, because they are dependent on the center coordinates. For pre API-18, coordinates will be calculated relative to customBadgeParent because the BadgeDrawable will be set as the parent's foreground.

Parameters
anchorView View: This badge's anchor.

customBadgeParent ViewGroup: An optional parent view that will set this BadgeDrawable as its foreground.

updateBadgeCoordinates

public void updateBadgeCoordinates (View anchorView, 
                FrameLayout customBadgeParent)

Calculates and updates this badge's center coordinates based on its anchor's bounds. Internally also updates this BadgeDrawable BadgeDrawable's bounds, because they are dependent on the center coordinates.

For pre API-18, if no customBadgeParent is specified, optionally wrap the anchor in a FrameLayout (if it's not done already) that will be inserted into the anchor's view hierarchy and calculate the badge's coordinates the parent FrameLayout because the BadgeDrawable will be set as the parent's foreground.

Parameters
anchorView View: This badge's anchor.

customBadgeParent FrameLayout: An optional parent view that will set this BadgeDrawable as its foreground.

updateBadgeCoordinates

public void updateBadgeCoordinates (View anchorView)

Calculates and updates this badge's center coordinates based on its anchor's bounds. Internally also updates this BadgeDrawable BadgeDrawable's bounds, because they are dependent on the center coordinates.

For pre API-18, optionally wrap the anchor in a FrameLayout (if it's not done already) that will be inserted into the anchor's view hierarchy and calculate the badge's coordinates the parent FrameLayout because the BadgeDrawable will be set as the parent's foreground.

Parameters
anchorView View: This badge's anchor.