# Chips
[Chips](https://material.io/components/chips) are compact elements that
represent an input, attribute, or action.
**Contents**
* [Using chips](#using-chips)
* [Assist chip](#assist-chip)
* [Filter chip](#filter-chip)
* [Input chip](#input-chip)
* [Suggestion chip](#suggestion-chip)
* [Theming chips](#theming-chips)
## Using chips
Before you can use Material chips, you need to add a dependency to the Material
Components for Android library. For more information, go to the
[Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
page.
Chips allow users to enter information, make selections, filter content, or
trigger actions. While buttons are expected to appear consistently and with
familiar calls to action, chips should appear dynamically as a group of multiple
interactive elements.
### Usage
A `Chip` can be added in a layout with the following:
```xml
```
Changes to a chip can be observed with the following:
```kt
chip.setOnClickListener {
// Responds to chip click
}
chip.setOnCloseIconClickListener {
// Responds to chip's close icon click if one is present
}
chip.setOnCheckedChangeListener { chip, isChecked ->
// Responds to chip checked/unchecked
}
```
### Making chips accessible
Chips support content labeling for accessibility and are readable by most screen
readers, such as TalkBack. Text rendered in chips is automatically provided to
accessibility services. Additional content labels are usually unnecessary.
#### Touch target
The `Widget.Material3.Chip.*` styles use an
[InsetDrawable](https://developer.android.com/reference/android/graphics/drawable/InsetDrawable)
to extend the chip's touch target when necessary to meet Android's recommended
[accessibility touch target size](https://support.google.com/accessibility/android/answer/7101858).
Developers can override a chip's minimum touch target size using
`app:chipMinTouchTargetSize`. Developers can set whether the chip should extend
its bounds to meet the minimum touch target using `app:ensureMinTouchTargetSize`
(true by default).
#### RTL-friendly chip layout
Call `setLayoutDirection(int)` with `View.LAYOUT_DIRECTION_LOCALE` to ensure
that the chip's ancestor `TextView` renders the text with proper paddings.
Without this, the initial rendering may look like the text has its padding set
according to LTR direction.
```kt
chip.layoutDirection = View.LAYOUT_DIRECTION_LOCALE
```
### Grouping chips with `ChipGroup`
Chips are most commonly used in groups. We recommend using `ChipGroup` because
it is purpose-built to handle multi-chip layouts and behavior patterns, as
opposed to a `ViewGroup` such as `RecyclerView`. A `ChipGroup` contains a set of
`Chip`s and manages their layout and multiple-exclusion scope, similarly to a
`RadioGroup`.
#### Layout Mode
A `ChipGroup` rearranges chips across multiple rows by default.
```xml
```
A `ChipGroup` can also constrain its chips to a single row using the
`app:singleLine` attribute. Using a single row may necessitate wrapping the
`ChipGroup` with a `HorizontalScrollView`.
```xml
```
#### Chip spacing
A `ChipGroup` can insert spacing between chips in a row or between rows of chips
using the `app:chipSpacing` attribute. Different horizontal and vertical spacing
can be set using the `app:chipSpacingHorizontal` and `app:chipSpacingVertical`
attributes.
**Note:** The `app:chipMinTouchTargetSize` will overrule vertical chip spacing
for lower amounts.
The following image shows a group of chips with
`app:chipSpacingHorizontal="42dp"`.
#### Multiple exclusion scope
The `app:singleSelection` attribute can be set to true on a `ChipGroup` in order
to toggle single-select and multi-select behaviors of child chips.
The `app:selectionRequired` attribute can be set to true on a `ChipGroup` to
prevent all child chips from being deselected - at least one option should be
chosen.
#### Handling checked chips
Changes to child chip's checked/unchecked state can be observed with the
following:
```kt
val checkedChipId = chipGroup.checkedChipId // Returns View.NO_ID if singleSelection = false
val checkedChipIds = chipGroup.checkedChipIds // Returns a list of the selected chips' IDs, if any
chipGroup.setOnCheckedChangeListener { group, checkedId ->
// Responds to child chip checked/unchecked
}
```
### Standalone `ChipDrawable`
A standalone `ChipDrawable` can be used in contexts that require a `Drawable`.
The most obvious use case is in text fields that "chipify" contacts, commonly
found in communications apps.
To use a `ChipDrawable`, first create a chip resource in `res/xml`. Note that
you must use the `
```
Input Chip is the default Material style for standalone `ChipDrawable`s, but you
can apply any of the other styles using the `style` attribute. All the
attributes on `Chip` can be applied to a `ChipDrawable` resource.
A ChipDrawable can then be inflated from this resource with the following:
```xml
val chipDrawable = ChipDrawable.createFromResource(context, R.xml.chip)
```
For example, consider an editable e-mail address field that converts addresses
to chips as they are typed and validated. We can combine `ChipDrawable` with
spans to add a chip to an `EditText`:
```kt
chip.setBounds(0, 0, chip.intrinsicWidth, chip.intrinsicHeight)
val span = ImageSpan(chip)
val text = editText.text!!
text.setSpan(span, 0, text.length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)
```
### Types
There are four types of chips: 1\. [assist](#assist-chip), 2\.
[filter](#filter-chip), 3\. [input](#input-chip),
4\.[suggestion](#suggestion-chip)
API and source code:
* `Chip`
* [Class definition](https://developer.android.com/reference/com/google/android/material/chip/Chip)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/Chip.java)
* `ChipGroup`
* [Class definition](https://developer.android.com/reference/com/google/android/material/chip/ChipGroup)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/ChipGroup.java)
* `ChipDrawable`
* [Class definition](https://developer.android.com/reference/com/google/android/material/chip/ChipDrawable)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/ChipDrawable.java)
## Assist chip
Assist chips represent smart or automated actions that can span multiple apps,
such as opening a calendar event from the home screen. Assist chips function as
though the user asked an assistant to complete the action.
### Assist chip example
The following example shows an activated assist chip.
In the layout:
```xml
```
## Filter chip
Filter chips use tags or descriptive words to filter content.
Filter chips clearly delineate and display options in a compact area. They are a
good alternative to toggle buttons or checkboxes.
### Filter chip example
The following example shows filter chips.
In the layout:
```xml
```
## Input chip
Input chips represent a discrete piece of information in compact form, such as
an entity (person, place, or thing) or text. They enable user input and verify
that input by converting text into chips.
### Input chip example
The following example shows input chips.
In the layout:
```xml
```
## Suggestion chip
Suggestion chips help narrow a user’s intent by presenting dynamically generated
suggestions, such as offering possible responses or providing search filters.
### Suggestion chip example
The following example shows suggestion chips.
In the layout:
```xml
```
### Anatomy and key properties
The following is an anatomy diagram of a chip:
1. Container
1. Text
1. Remove icon (optional)
1. Thumbnail (optional)
#### Container attributes
Element | Attribute | Related method(s) | Default value
-------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------
**Color** | `app:chipBackgroundColor` | `setChipBackgroundColor`
`setChipBackgroundColorResource`
`getChipBackgroundColor` | `?attr/colorOnSurface`
**Ripple color** | `app:rippleColor` | `setRippleColor`
`setRippleColorResource`
`getRippleColor` | `?attr/colorOnSecondaryContainer` at 12%
**Stroke width** | `app:chipStrokeWidth` | `setStrokeWidth`
`setChipStrokeWidthResource`
`getChipStrokeWidth` | `1dp`
**Stroke color** | `app:chipStrokeColor` | `setStrokeColor`
`setChipStrokeColorResource`
`getChipStrokeColor` | `?attr/colorOnSurface`
**Min height** | `app:chipMinHeight` | `setChipMinHeight`
`setChipMinHeightResource`
`getChipMinHeight` | `32dp`
**Padding** | `app:chipStartPadding`
`app:chipEndPadding` | `setChip*Padding`
`setChip*PaddingResource`
`getChip*Padding` | `4dp` (start)
`6dp` (end)
**Shape** | `app:shapeAppearance`
`shapeAppearanceOverlay` | `setShapeAppearanceModel`
`getShapeAppearanceModel` | `?attr/shapeAppearanceSmallComponent` with 8dp `cornerSize`
**Min touch target** | `app:chipMinTouchTargetSize`
`app:ensureMinTouchTargetSize` | `ensureAccessibleTouchTarget`
`setEnsureAccessibleTouchTarget`
`shouldEnsureAccessibleTouchTarget` | `48dp`
`true`
**Checkable** | `android:checkable` | `setCheckable`
`setCheckableResource`
`isCheckable` | `true` (input, suggestion, filter)
#### Thumbnail attributes
**Chip icon**
Element | Attribute | Related method(s) | Default value
-------------- | ----------------------------------------------- | --------------------------------------------------------------------- | -------------
**Icon** | `app:chipIcon` | `setChipIconVisible`
`isChipIconVisible` | `null`
**Visibility** | `app:chipIconVisible` | `setChipIcon`
`setChipIconResource`
`getChipIcon` | `true` (input and assist)
**Color** | `app:chipIconTint` | `setChipIconTint`
`setChipIconTintResource`
`getChipIconTint` | `null`
**Size** | `app:chipIconSize` | `setChipIconSize`
`setChipIconSizeResource`
`getChipIconSize` | `18dp`
**Padding** | `app:iconStartPadding`
`app:iconEndPadding` | `setIcon*Padding`
`setIcon*PaddingResource`
`getIcon*Padding` | `0dp`, `-2dp` (filter end padding)
**Checked icon**
If visible, the checked icon overlays the chip icon.
Element | Attribute | Related method(s) | Default value
-------------- | ------------------------ | ------------------------------------------------------------------------------ | -------------
**Icon** | `app:checkedIcon` | `setCheckedIconVisible`
`isCheckedIconVisible` | `@drawable/ic_m3_chip_checked_circle`
**Visibility** | `app:checkedIconVisible` | `setCheckedIcon`
`setCheckedIconResource`
`getCheckedIcon` | `true` (input, filter)
**Color** | `app:checkedIconTint` | `setCheckedIconTint`
`setCheckedIconTintResource`
`getCheckedIconTint` | `null`
#### Text attributes
Element | Attribute | Related method(s) | Default value
-------------- | ----------------------------------------------- | --------------------------------------------------------------------------- | -------------
**Text label** | `android:text` | `setChipText`
`setChipTextResource`
`getChipText` | `null`
**Color** | `android:textColor` | `setTextColor`
`getTextColors` | `?attr/colorOnSurfaceVariant`
**Typography** | `android:textAppearance` | `setTextAppearance`
`setTextAppearanceResource`
`getTextAppearance` | `?attr/textAppearanceLabelLarge`
**Padding** | `app:textStartPadding`
`app:textEndPadding` | `setText*Padding`
`setText*PaddingResource`
`getText*Padding` | `8dp` (start)
`6dp` (end)
#### Remove (close) icon attributes
Element | Attribute | Related method(s) | Default value
----------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------
**Icon** | `app:closeIcon` | `setCloseIcon`
`setCloseIconResource`
`getCloseIcon` | `@drawable/ic_mtrl_chip_close_circle`
**Visibility** | `app:closeIconVisible` | `setCloseIconVisible`
`isCloseIconVisible` | `true` for input
**Color** | `app:closeIconTint` | `setCloseIconTint`
`setCloseIconTintResource`
`getCloseIconTint` | `?attr/colorOnSurfaceVariant`
**Size** | `app:closeIconSize` | `setCloseIconSize`
`setCloseIconSizeResource`
`getCloseIconSize` | `18dp`
**Padding** | `app:closeIconStartPadding`
`app:closeIconEndPadding` | `setCloseIcon*Padding`
`setCloseIcon*PaddingResource`
`getCloseIcon*Padding` | `4dp` input end padding
**Content description** | N/A | `setCloseIconContentDescription`
`getCloseIconContentDescription` | `@string/mtrl_chip_close_icon_content_description`
#### `ChipGroup` attributes
Element | Attribute | Related method(s) | Default value
------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------
**Layout** | `app:singleLine` | `setSingleLine`
`isSingleLine` | `false`
**Selection** | `app:singleSelection`
`app:selectionRequired` | `setSingleSelection*`
`isSingleSelection*` | `false`
`false`
**Spacing** | `app:chipSpacing`
`app:chipSpacingHorizontal`
`chipSpacingVertical` | `setSpacing*`
`setChipSpacing*Resource`
`getSpacing*` | `8dp`
#### Styles
Element | Style
------------------------------- | ----------------------------------
**Default style (assist chip)** | `Widget.Material3.Chip.Assist`
**Input chip** | `Widget.Material3.Chip.Input`
**Suggestion chip** | `Widget.Material3.Chip.Suggestion`
**Filter chip** | `Widget.Material3.Chip.Filter`
**`ChipGroup` style** | `Widget.Material3.ChipGroup`
#### Theme attributes
Element | Theme attribute | Default style
------------------ | --------------------------- | -------------
**`Chip`** | `?attr/chipStyle` | `Widget.Material3.Chip.Assist`
**`ChipGroup`** | `?attr/chipGroupStyle` | `Widget.Material3.ChipGroup`
**`ChipDrawable`** | `?attr/chipStandaloneStyle` | `Widget.Material3.Chip.Input`
See the full list of
[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/res/values/styles.xml)
and
[attributes](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/res/values/attrs.xml).
## Theming chips
Chips support [Material Theming](https://material.io/components/chips/#theming),
which customizes color, typography and shape.
### Chip theming example
API and source code:
* `Chip`
* [Class definition](https://developer.android.com/reference/com/google/android/material/chip/Chip)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/Chip.java)
* `ChipGroup`
* [Class definition](https://developer.android.com/reference/com/google/android/material/chip/ChipGroup)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/ChipGroup.java)
* `ChipDrawable`
* [Class definition](https://developer.android.com/reference/com/google/android/material/chip/ChipDrawable)
* [Class source](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/chip/ChipDrawable.java)
The following example shows chips with Material Theming.
#### Implementing chip theming
Use theme attributes and styles in `res/values/styles.xml`, which applies the
theme to all chips and affects other components:
```xml
```
in `color/stroke_tint.xml`:
```xml