diff --git a/docs/components/chip.md b/docs/components/chip.md new file mode 100644 index 0000000000..5601417b58 --- /dev/null +++ b/docs/components/chip.md @@ -0,0 +1,480 @@ + + + + + +# Chips + + + + + + + + + + +**This documentation is fully rendered on the +[Material Web catalog](https://material-web.dev/components/chips/)** + + + + +[Chips](https://m3.material.io/components/chips) help people 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. + + + +Two collections of filter chips, with some options selected and some unselected. + + + +* [Design article](https://m3.material.io/components/chips) +* API Documentation (*coming soon*) +* [Source code](https://github.com/material-components/material-web/tree/main/chips) + + +## Types + +1. [Assist chip](#assist-chip) +1. [Filter chip](#filter-chip) +1. [Input chip](#input-chip) +1. [Suggestion chip](#suggestion-chip) + + + + + + + +## Usage + +Choose the type of chip based on its purpose and author. + +- **Assist** chips are common actions, such as adding an event to a calendar. +- **Filter** chips are tags used to filter content, such as shopping + categories. +- **Input** chips are pieces of information entered by a user, such as event + attendees. +- **Suggestion** chips represent dynamic suggestions for user input, such as + text message replies. + + + + + + +```html + + + + +``` + +### Chip sets + + + +Chips should always appear in a set. Use the same type of chip for chip set +children. + + + + + + +```html +

New event

+ + + + + +

Favorite foods

+ + + + + +``` + +### Icons + +All chips may display an optional icon. Input chips can specify if an avatar +picture is displayed. + + + + + + + +```html + + event + + + + + +``` + +### Elevated + +Assist, filter, and suggestion chips can be elevated if the placement requires +protection, such as on top of an image. + + + + + + + +```html +
+ + + + + +
+``` + +## Accessibility + +Add an +[`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) +attribute to chip sets without labels or chips whose labels need to be more +descriptive. + +```html + + + + + + +``` + +## Assist chip + + + +[Assist chips](https://m3.material.io/components/chips/guidelines#5dd1928c-1476-4029-bdc5-fde66fc0dcb1) +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. They should appear dynamically and contextually in a UI. + + + + + + + +```html +

A restaraunt location

+ + + calendar + + + map + + +``` + +## Filter chip + + + +[Filter chips](https://m3.material.io/components/chips/guidelines#8d453d50-8d8e-43aa-9ae3-87ed134d2e64) +use tags or descriptive words to filter content. They can be a good alternative +to toggle buttons or checkboxes. + + + + + + + +```html +

Choose where to share

+ + + + + + +``` + +### Single select + +Filter chip sets can add a `single-select` attribute to only allow a single +filter chip to be selected at one time. + + + + + + + +```html +

Shopping category

+ + + + + +``` + +### Removable + +Filter chips can optionally be removable from the chip set. Removable chips have +a trailing remove icon. + + + + + + + +```html +

Colors

+ + + + + + +``` + +## Input chip + + + +[Input chips](https://m3.material.io/components/chips/guidelines#4d2d5ef5-3fcd-46e9-99f2-067747b2393f) +represent discrete pieces of information entered by a user, such as Gmail +contacts or filter options within a search field. + +Input chips whose icons are user images may add the `avatar` attribute to +display the image in a larger circle. + + + + + + + +```html + + + + + + + + + + +``` + +### Remove-only + +All input chips are removable. If an input chip does not have an action +associated with clicking on it, it may be marked as `remove-only`. + + + + + + + +```html +

Favorite movies

+ + + + +``` + +## Suggestion chip + + + +[Suggestion chips](https://m3.material.io/components/chips/guidelines#36d7bb16-a9bf-4cf6-a73d-8e05510d66a7) +help narrow a user’s intent by presenting dynamically generated suggestions, +such as possible responses or search filters. + + + + + + + +```html +

Suggested reply

+ + + + + +``` + +## Theming + +Chips support [Material theming](../theming.md) and can be customized in terms +of color, typography, and shape. + +### Assist chip tokens + +Token | Default value +----------------------------------- | -------------------------------- +`--md-assist-chip-outline-color` | `--md-sys-color-outline` +`--md-assist-chip-container-shape` | `8px` +`--md-assist-chip-icon-size` | `18px` +`--md-assist-chip-label-text-color` | `--md-sys-color-on-surface` +`--md-assist-chip-label-text-type` | `--md-sys-typescale-label-large` + +* [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-assist-chip.scss) + + +### Assist chip example + + + + + + +```html + + + +``` + +### Filter chip tokens + +Token | Default value +------------------------------------------- | ------------- +`--md-filter-chip-selected-container-color` | `--md-sys-color-secondary-container` +`--md-filter-chip-outline-color` | `--md-sys-color-outline` +`--md-filter-chip-container-shape` | `8px` +`--md-filter-chip-icon-size` | `18px` +`--md-filter-chip-label-text-color` | `--md-sys-color-on-surface` +`--md-filter-chip-label-text-type` | `--md-sys-typescale-label-large` + +* [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filter-chip.scss) + + +### Filter chip example + + + + + + +```html + + + +``` + +### Input chip tokens + +Token | Default value +---------------------------------- | -------------------------------- +`--md-input-chip-outline-color` | `--md-sys-color-outline` +`--md-input-chip-container-shape` | `8px` +`--md-input-chip-icon-size` | `18px` +`--md-input-chip-label-text-color` | `--md-sys-color-on-surface` +`--md-input-chip-label-text-type` | `--md-sys-typescale-label-large` + +* [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-input-chip.scss) + + +### Input chip example + + + + + + +```html + + + +``` + +### Suggestion chip tokens + +Token | Default value +--------------------------------------- | -------------------------------- +`--md-suggestion-chip-outline-color` | `--md-sys-color-outline` +`--md-suggestion-chip-container-shape` | `8px` +`--md-suggestion-chip-icon-size` | `18px` +`--md-suggestion-chip-label-text-color` | `--md-sys-color-on-surface` +`--md-suggestion-chip-label-text-type` | `--md-sys-typescale-label-large` + +* [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-suggestion-chip.scss) + + +### Suggestion chip example + + + + + + +```html + + + +``` diff --git a/docs/components/images/chips/hero.png b/docs/components/images/chips/hero.png new file mode 100644 index 0000000000..d743dcc974 Binary files /dev/null and b/docs/components/images/chips/hero.png differ