BadgeDrawable

public class 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 com.google.android.material.bottomnavigation.BottomNavigationView. To create an instance of BadgeDrawable, use create or createFromResource. How to add and display a BadgeDrawable on top of its anchor view depends on the API level:

For API 18+ (APIs supported by android.view.ViewOverlay)

  • Add BadgeDrawable as a android.view.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. 
BadgeDrawable badgeDrawable = BadgeDrawable.create(context);
badgeDrawable.setVisible(true);
BadgeUtils.attachBadgeDrawable(badgeDrawable, anchor);

For Pre API-18

  • Set BadgeDrawable as the foreground of the anchor view's FrameLayout ancestor using attachBadgeDrawable (This helper class is currently experimental).
  • Update the BadgeDrawable BadgeDrawable's coordinates (center and bounds) based on its anchor view (relative to its FrameLayout ancestor's coordinate space), using updateBadgeCoordinates.
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 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, setVerticalOffset

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 types
@Retention(value = RetentionPolicy.SOURCE)
public annotation BadgeDrawable.BadgeGravity

Position the badge can be set to.

Constants
static final int

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

The badge's edge is fixed at the end and grows towards the start.
static final int

The badge's edge is fixed at the start and grows towards the end.
static final int

This field is deprecated.

Bottom badge gravities are deprecated in favor of top gravities; use TOP_START or TOP_END instead.
static final int

This field is deprecated.

Bottom badge gravities are deprecated in favor of top gravities; use TOP_START or TOP_END instead.
static final int

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

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

Public methods
void

Clears the badge's number.
void

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
int

Returns this badge's background color.
int
Locale

Returns the Locale used to show badge numbers.
int

Returns this badge's text color.
CharSequence
FrameLayout

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

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

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

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

Returns the badge horizontal padding in pixels.
int

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

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

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

Returns this badge's max character count.
int

Returns this badge's max number.
int

Returns the badge's number.
int
abstract int[]
String

Returns the badge's text.
int

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

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

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

Returns the badge vertical padding in pixels.
boolean

Returns whether this badge will display a number.
boolean

Returns whether the badge will display a text.
boolean
boolean
onStateChange(int[] state)
void
setAlpha(int alpha)
void
setAutoAdjustToWithinGrandparentBounds(
    boolean autoAdjustToWithinGrandparentBounds
)

This method is deprecated.

Badges now automatically adjust their bounds within the first ancestor view that * clips its children.
void
setBackgroundColor(int backgroundColor)

Sets this badge's background color.
void
setBadgeFixedEdge(int fixedEdge)

Sets this badge's fixed edge.
void

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

Sets the Locale used to show badge numbers.
void
setBadgeTextColor(int badgeTextColor)

Sets this badge's text color.
void

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

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

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

Sets this badge without text's shape appearance overlay resource.
void
setColorFilter(ColorFilter colorFilter)
void

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

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

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

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

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

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

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

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

Sets the badge's text.
void

Sets this badge's text appearance resource.
void

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

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

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 setVisible with the restart parameter hardcoded to false.
void
updateBadgeCoordinates(View anchorView)

Calculates and updates this badge's center coordinates based on its anchor's bounds.
void
updateBadgeCoordinates(View anchorView, FrameLayout customBadgeParent)

Calculates and updates this badge's center coordinates based on its anchor's bounds.
void
updateBadgeCoordinates(View anchorView, ViewGroup customBadgeParent)

This method is deprecated.

use updateBadgeCoordinates instead.

Constants

BADGE_CONTENT_NOT_TRUNCATED

public static final int BADGE_CONTENT_NOT_TRUNCATED = -2

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

BADGE_FIXED_EDGE_END

public static final int BADGE_FIXED_EDGE_END = 1

The badge's edge is fixed at the end and grows towards the start.

BADGE_FIXED_EDGE_START

public static final int BADGE_FIXED_EDGE_START = 0

The badge's edge is fixed at the start and grows towards the end.

BOTTOM_END

public static final int BOTTOM_END

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

BOTTOM_START

public static final int BOTTOM_START

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

TOP_END

public static final int TOP_END

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

TOP_START

public static final int TOP_START

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

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.

createFromResource

public static BadgeDrawable createFromResource(Context context, int id)

Returns a BadgeDrawable from the given XML resource. All attributes from 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"/>

draw

public void draw(Canvas canvas)

getAlpha

public int getAlpha()

getBackgroundColor

public int getBackgroundColor()

Returns this badge's background color.

ref com.google.android.material.R.styleable#Badge_backgroundColor

See also
setBackgroundColor

getBadgeGravity

@BadgeDrawable.BadgeGravity
public int getBadgeGravity()

getBadgeNumberLocale

public Locale getBadgeNumberLocale()

Returns the Locale used to show badge numbers.

getBadgeTextColor

public int getBadgeTextColor()

Returns this badge's text color.

ref com.google.android.material.R.styleable#Badge_badgeTextColor

See also
setBadgeTextColor

getContentDescription

public CharSequence getContentDescription()

getCustomBadgeParent

public FrameLayout getCustomBadgeParent()

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

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.

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.

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).

getHorizontalPadding

public int getHorizontalPadding()

Returns the badge horizontal padding in pixels.

getIntrinsicHeight

public int getIntrinsicHeight()

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

getIntrinsicWidth

public int getIntrinsicWidth()

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

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.

getMaxCharacterCount

public int getMaxCharacterCount()

Returns this badge's max character count.

ref com.google.android.material.R.styleable#Badge_maxCharacterCount

See also
setMaxCharacterCount

getMaxNumber

public int getMaxNumber()

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

ref com.google.android.material.R.styleable#Badge_maxNumber

See also
setMaxNumber

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

ref com.google.android.material.R.styleable#Badge_number

See also
setNumber

getOpacity

public int getOpacity()

getState

public abstract int[] getState()

getText

public String getText()

Returns the badge's text.

ref com.google.android.material.R.styleable#Badge_badgeText

See also
setText

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.

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.

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).

getVerticalPadding

public int getVerticalPadding()

Returns the badge vertical padding in pixels.

hasNumber

public boolean hasNumber()

Returns whether this badge will display a number.

hasText

public boolean hasText()

Returns whether the badge will display a text.

isStateful

public boolean isStateful()

onStateChange

public boolean onStateChange(int[] state)

setAlpha

public void setAlpha(int alpha)

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
boolean autoAdjustToWithinGrandparentBounds

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.

ref com.google.android.material.R.styleable#Badge_backgroundColor

Parameters
int backgroundColor

This badge's background color.

setBadgeFixedEdge

public void setBadgeFixedEdge(int fixedEdge)

Sets this badge's fixed edge. The badge does not grow in the direction of the fixed edge.

Parameters
int fixedEdge

Constant representing a BadgeFixedEdge value. The two options are BADGE_FIXED_EDGE_START and BADGE_FIXED_EDGE_END.

setBadgeGravity

public void setBadgeGravity(@BadgeDrawable.BadgeGravity int gravity)

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

Parameters
@BadgeDrawable.BadgeGravity int gravity

Constant representing one of the possible 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.

setBadgeTextColor

public void setBadgeTextColor(int badgeTextColor)

Sets this badge's text color.

ref com.google.android.material.R.styleable#Badge_badgeTextColor

Parameters
int badgeTextColor

This badge's text color.

setBadgeWithTextShapeAppearance

public void setBadgeWithTextShapeAppearance(int id)

Sets this badge with text's shape appearance resource.

ref com.google.android.material.R.styleable#Badge_badgeWithTextShapeAppearance

Parameters
int id

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.

ref com.google.android.material.R.styleable#Badge_badgeWithTextShapeAppearanceOverlay

Parameters
int id

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.

ref com.google.android.material.R.styleable#Badge_badgeShapeAppearance

Parameters
int id

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.

ref com.google.android.material.R.styleable#Badge_badgeShapeAppearanceOverlay

Parameters
int id

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

setColorFilter

public void setColorFilter(ColorFilter colorFilter)

setContentDescriptionExceedsMaxBadgeNumberStringResource

public void setContentDescriptionExceedsMaxBadgeNumberStringResource(
    int stringsResource
)

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

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.

setContentDescriptionNumberless

public void setContentDescriptionNumberless(CharSequence charSequence)

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

setContentDescriptionQuantityStringsResource

public void setContentDescriptionQuantityStringsResource(int stringsResource)

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

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
int px

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
int px

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
int px

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.

ref com.google.android.material.R.styleable#Badge_badgeWidePadding

Parameters
int horizontalPadding

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
int px

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.

ref com.google.android.material.R.styleable#Badge_maxCharacterCount

Parameters
int maxCharacterCount

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.

ref com.google.android.material.R.styleable#Badge_maxNumber

Parameters
int maxNumber

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.

ref com.google.android.material.R.styleable#Badge_number

Parameters
int number

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.

ref com.google.android.material.R.styleable#Badge_badgeText

See also
getText

setTextAppearance

public void setTextAppearance(int id)

Sets this badge's text appearance resource.

ref com.google.android.material.R.styleable#Badge_badgeTextAppearance

Parameters
int id

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
int px

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
int px

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
int px

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.

ref com.google.android.material.R.styleable#Badge_badgeVerticalPadding

Parameters
int verticalPadding

badge's vertical padding

setVisible

public void setVisible(boolean visible)

Convenience wrapper method for setVisible with the restart parameter hardcoded to false.

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.

Parameters
View anchorView

This badge's anchor.

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.

Parameters
View anchorView

This badge's anchor.
FrameLayout customBadgeParent

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

updateBadgeCoordinates

public void updateBadgeCoordinates(View anchorView, ViewGroup 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, coordinates will be calculated relative to customBadgeParent because the BadgeDrawable will be set as the parent's foreground.

Parameters
View anchorView

This badge's anchor.
ViewGroup customBadgeParent

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