docs(button): add docs
PiperOrigin-RevId: 509390889
@ -15,6 +15,7 @@
|
||||
display: inline-flex;
|
||||
position: relative;
|
||||
writing-mode: horizontal-tb;
|
||||
fill: currentColor;
|
||||
color: var(--_with-icon-icon-color);
|
||||
font-size: var(--_with-icon-icon-size);
|
||||
inline-size: var(--_with-icon-icon-size);
|
||||
|
290
docs/components/button.md
Normal file
@ -0,0 +1,290 @@
|
||||
# Buttons
|
||||
|
||||
<!--*
|
||||
# Document freshness: For more information, see go/fresh-source.
|
||||
freshness: { owner: 'lizmitchell' reviewed: '2023-01-26' }
|
||||
*-->
|
||||
|
||||
<!-- go/md-button -->
|
||||
|
||||
<!-- [TOC] -->
|
||||
|
||||
[Buttons](https://m3.material.io/components/buttons)<!-- {.external} --> help people
|
||||
initiate actions, from sending an email, to sharing a document, to liking a
|
||||
post.
|
||||
|
||||
There are five types of common buttons: elevated, filled, filled tonal,
|
||||
outlined, and text.
|
||||
|
||||
![The 5 types of common buttons](images/button/hero.png "Elevated, filled, filled tonal, outlined, and text buttons")
|
||||
|
||||
* [Design article](https://m3.material.io/components/buttons) <!-- {.external} -->
|
||||
* API Documentation (*coming soon*)
|
||||
* [Source code](https://github.com/material-components/material-web/tree/master/button)
|
||||
<!-- {.external} -->
|
||||
|
||||
## Types
|
||||
|
||||
1. [Elevated button](#elevated-button)
|
||||
1. [Filled button](#filled-button)
|
||||
1. [Filled tonal button](#filled-tonal-button)
|
||||
1. [Outlined button](#outlined-button)
|
||||
1. [Text button](#text-button)
|
||||
|
||||
## Usage
|
||||
|
||||
Buttons have label text that describes the action that will occur if a user taps
|
||||
a button.
|
||||
|
||||
![Accessibility text](images/button/usage.png "Optional caption text")
|
||||
|
||||
```html
|
||||
<md-outlined-button label="Back"></md-outlined-button>
|
||||
<md-filled-button label="Complete"></md-filled-button>
|
||||
```
|
||||
|
||||
### Icon
|
||||
|
||||
An icon may optionally be added to a button to help communicate the button's
|
||||
action and help draw attention.
|
||||
|
||||
![Accessibility text](images/button/usage-icon.png "Optional caption text")
|
||||
|
||||
```html
|
||||
<md-tonal-button label="Send">
|
||||
<svg slot="icon" viewBox="0 0 48 48"><path d="M6 40V8l38 16Zm3-4.65L36.2 24 9 12.5v8.4L21.1 24 9 27Zm0 0V12.5 27Z"/></svg>
|
||||
</md-tonal-button>
|
||||
|
||||
<md-text-button label="Open" trailingicon>
|
||||
<svg slot="icon" viewBox="0 0 48 48"><path d="M9 42q-1.2 0-2.1-.9Q6 40.2 6 39V9q0-1.2.9-2.1Q7.8 6 9 6h13.95v3H9v30h30V25.05h3V39q0 1.2-.9 2.1-.9.9-2.1.9Zm10.1-10.95L17 28.9 36.9 9H25.95V6H42v16.05h-3v-10.9Z"/></svg>
|
||||
</md-text-button>
|
||||
```
|
||||
|
||||
## Accessibility
|
||||
|
||||
Add an
|
||||
[`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)<!-- {.external} -->
|
||||
attribute to buttons whose labels need a more descriptive label.
|
||||
|
||||
```html
|
||||
<md-elevated-button label="Add" aria-label="Add a new contact"></md-elevated-button>
|
||||
```
|
||||
|
||||
## Elevated button
|
||||
|
||||
<!-- go/md-elevated-button -->
|
||||
|
||||
[Elevated buttons](https://m3.material.io/components/buttons/guidelines#4e89da4d-a8fa-4e20-bb8d-b8a93eff3e3e)<!-- {.external} -->
|
||||
are essentially filled tonal buttons with a shadow. To prevent shadow creep,
|
||||
only use them when absolutely necessary, such as when the button requires visual
|
||||
separation from a patterned background.
|
||||
|
||||
![An elevated button](images/button/usage-elevated-button.png)
|
||||
|
||||
```html
|
||||
<md-elevated-button label="Elevated"></md-elevated-button>
|
||||
```
|
||||
|
||||
## Filled button
|
||||
|
||||
<!-- go/md-filled-button -->
|
||||
|
||||
[Filled buttons](https://m3.material.io/components/buttons/guidelines#9ecffdb3-ef29-47e7-8d5d-f78b404fcafe)<!-- {.external} -->
|
||||
have the most visual impact after the FAB, and should be used for important,
|
||||
final actions that complete a flow, like Save, Join now, or Confirm.
|
||||
|
||||
![A filled button](images/button/usage-filled-button.png)
|
||||
|
||||
```html
|
||||
<md-filled-button label="Filled"></md-filled-button>
|
||||
```
|
||||
|
||||
## Filled tonal button
|
||||
|
||||
<!-- go/md-tonal-button -->
|
||||
|
||||
A
|
||||
[filled tonal button](https://m3.material.io/components/buttons/guidelines#07a1577b-aaf5-4824-a698-03526421058b)<!-- {.external} -->
|
||||
is an alternative middle ground between filled and outlined buttons. They're
|
||||
useful in contexts where a lower-priority button requires slightly more emphasis
|
||||
than an outline would give, such as "Next" in an onboarding flow.
|
||||
|
||||
![A filled tonal button](images/button/usage-filled-tonal-button.png)
|
||||
|
||||
```html
|
||||
<md-tonal-button label="Tonal"></md-tonal-button>
|
||||
```
|
||||
|
||||
## Outlined button
|
||||
|
||||
<!-- go/md-outlined-button -->
|
||||
|
||||
[Outlined buttons](https://m3.material.io/components/buttons/guidelines#3742b09f-c224-43e0-a83e-541bd29d0f05)<!-- {.external} -->
|
||||
are medium-emphasis buttons. They contain actions that are important, but aren’t
|
||||
the primary action in an app.
|
||||
|
||||
![An outlined button](images/button/usage-outlined-button.png)
|
||||
|
||||
```html
|
||||
<md-outlined-button label="Outlined"></md-outlined-button>
|
||||
```
|
||||
|
||||
## Text button
|
||||
|
||||
<!-- go/md-text-button -->
|
||||
|
||||
[Text buttons](https://m3.material.io/components/buttons/guidelines#c9bcbc0b-ee05-45ad-8e80-e814ae919fbb)<!-- {.external} -->
|
||||
are used for the lowest priority actions, especially when presenting multiple
|
||||
options.
|
||||
|
||||
![A text button](images/button/usage-text-button.png)
|
||||
|
||||
```html
|
||||
<md-text-button label="Text"></md-text-button>
|
||||
```
|
||||
|
||||
## Theming
|
||||
|
||||
Button supports [Material theming](../theming.md) and can be customized in terms
|
||||
of color, typography, and shape.
|
||||
|
||||
### Elevated button tokens
|
||||
|
||||
Token | Default value
|
||||
--------------------------------------- | ---------------------------
|
||||
`--md-elevated-button-container-color` | `--md-sys-color-surface`
|
||||
`--md-elevated-button-container-shape` | `9999px`
|
||||
`--md-elevated-button-label-text-color` | `--md-sys-color-on-surface`
|
||||
`--md-elevated-button-label-text-font` | `"Roboto"`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-elevated-button.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Elevated button example
|
||||
|
||||
![Image of an elevated button with a different theme applied](images/button/theming-elevated-button.png "Elevated button theming example.")
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-elevated-button-container-shape: 0px;
|
||||
--md-elevated-button-label-text-font: system-ui;
|
||||
--md-sys-color-surface: #FAFDFC;
|
||||
--md-sys-color-on-surface: #191C1C;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-elevated-button label="Elevated"></md-elevated-button>
|
||||
```
|
||||
|
||||
### Filled button tokens
|
||||
|
||||
Token | Default value
|
||||
------------------------------------- | ---------------------------
|
||||
`--md-filled-button-container-color` | `--md-sys-color-primary`
|
||||
`--md-filled-button-container-shape` | `9999px`
|
||||
`--md-filled-button-label-text-color` | `--md-sys-color-on-primary`
|
||||
`--md-filled-button-label-text-font` | `"Roboto"`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-filled-button.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Filled button example
|
||||
|
||||
![Image of a filled button with a different theme applied](images/button/theming-filled-button.png "Filled button theming example.")
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-filled-button-container-shape: 0px;
|
||||
--md-filled-button-label-text-font: system-ui;
|
||||
--md-sys-color-primary: #006A6A;
|
||||
--md-sys-color-on-primary: #FFFFFF;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-filled-button label="Filled"></md-filled-button>
|
||||
```
|
||||
|
||||
### Filled tonal button tokens
|
||||
|
||||
Token | Default value
|
||||
------------------------------------ | ---------------------------------------
|
||||
`--md-tonal-button-container-color` | `--md-sys-color-secondary-container`
|
||||
`--md-tonal-button-container-shape` | `9999px`
|
||||
`--md-tonal-button-label-text-color` | `--md-sys-color-on-secondary-container`
|
||||
`--md-tonal-button-label-text-font` | `"Roboto"`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-filled-tonal-button.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Filled tonal button example
|
||||
|
||||
![Image of a filled tonal button with a different theme applied](images/button/theming-filled-tonal-button.png "Filled tonal button theming example.")
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-tonal-button-container-shape: 0px;
|
||||
--md-tonal-button-label-text-font: system-ui;
|
||||
--md-sys-color-secondary-container: #CCE8E7;
|
||||
--md-sys-color-on-secondary-container: #051F1F;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-tonal-button label="Tonal"></md-tonal-button>
|
||||
```
|
||||
|
||||
### Outlined button tokens
|
||||
|
||||
Token | Default value
|
||||
--------------------------------------- | ------------------------
|
||||
`--md-outlined-button-outline-color` | `--md-sys-color-outline`
|
||||
`--md-outlined-button-container-shape` | `9999px`
|
||||
`--md-outlined-button-label-text-color` | `--md-sys-color-primary`
|
||||
`--md-outlined-button-label-text-font` | `"Roboto"`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-outlined-button.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Outlined button example
|
||||
|
||||
![Image of an outlined button with a different theme applied](images/button/theming-outlined-button.png "Outlined button theming example.")
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-outlined-button-container-shape: 0px;
|
||||
--md-outlined-button-label-text-font: system-ui;
|
||||
--md-sys-color-primary: #006A6A;
|
||||
--md-sys-color-outline: #6F7979;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-outlined-button label="Outlined"></md-outlined-button>
|
||||
```
|
||||
|
||||
### Text button tokens
|
||||
|
||||
Token | Default value
|
||||
----------------------------------- | ------------------------
|
||||
`--md-text-button-label-text-color` | `--md-sys-color-primary`
|
||||
`--md-text-button-label-text-font` | `"Roboto"`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-text-button.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Text button example
|
||||
|
||||
![Image of a text button with a different theme applied](images/button/theming-text-button.png "Text button theming example.")
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-text-button-label-text-font: system-ui;
|
||||
--md-sys-color-primary: #006A6A;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-text-button label="Text"></md-text-button>
|
||||
```
|
@ -80,7 +80,7 @@ Token | Default value
|
||||
`--md-checkbox-selected-icon-color` | `--md-sys-color-on-primary`
|
||||
`--md-checkbox-container-shape` | `2px`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-checkbox.scss#L28-L135)
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-checkbox.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Example
|
||||
|
@ -90,7 +90,7 @@ Token | Default value
|
||||
`--md-divider-color` | `--md-sys-color-outline-variant`
|
||||
`--md-divider-thickness` | `1px`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-divider.scss#L22-L23)
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/master/tokens/v0_152/_md-comp-divider.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Example
|
||||
|
BIN
docs/components/images/button/hero.png
Normal file
After Width: | Height: | Size: 26 KiB |
BIN
docs/components/images/button/theming-elevated-button.png
Normal file
After Width: | Height: | Size: 4.3 KiB |
BIN
docs/components/images/button/theming-filled-button.png
Normal file
After Width: | Height: | Size: 2.3 KiB |
BIN
docs/components/images/button/theming-filled-tonal-button.png
Normal file
After Width: | Height: | Size: 2.4 KiB |
BIN
docs/components/images/button/theming-outlined-button.png
Normal file
After Width: | Height: | Size: 3.5 KiB |
BIN
docs/components/images/button/theming-text-button.png
Normal file
After Width: | Height: | Size: 2.0 KiB |
BIN
docs/components/images/button/usage-elevated-button.png
Normal file
After Width: | Height: | Size: 7.7 KiB |
BIN
docs/components/images/button/usage-filled-button.png
Normal file
After Width: | Height: | Size: 3.6 KiB |
BIN
docs/components/images/button/usage-filled-tonal-button.png
Normal file
After Width: | Height: | Size: 3.6 KiB |
BIN
docs/components/images/button/usage-icon.png
Normal file
After Width: | Height: | Size: 6.9 KiB |
BIN
docs/components/images/button/usage-outlined-button.png
Normal file
After Width: | Height: | Size: 5.6 KiB |
BIN
docs/components/images/button/usage-text-button.png
Normal file
After Width: | Height: | Size: 2.0 KiB |
BIN
docs/components/images/button/usage.png
Normal file
After Width: | Height: | Size: 9.6 KiB |