mirror of
https://github.com/material-components/material-web.git
synced 2026-01-09 07:21:09 +08:00
docs(select): add select documentation
PiperOrigin-RevId: 566674810
This commit is contained in:
Andrew Jakubowicz
Copybara-Service
parent
6e54048f1e
commit
e3b3d86fa9
9
catalog/src/hydration-entrypoints/components/select.ts
Normal file
9
catalog/src/hydration-entrypoints/components/select.ts
Normal file
@ -0,0 +1,9 @@
|
||||
/**
|
||||
* @license
|
||||
* Copyright 2023 Google LLC
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
|
||||
import '@material/web/select/select-option.js';
|
||||
import '@material/web/select/outlined-select.js';
|
||||
import '@material/web/select/filled-select.js';
|
||||
25
docs/components/figures/select/theming-filled.html
Normal file
25
docs/components/figures/select/theming-filled.html
Normal file
@ -0,0 +1,25 @@
|
||||
<div class="figure-wrapper">
|
||||
<figure
|
||||
class="styled-example filled"
|
||||
title="Filled select theming example"
|
||||
aria-label="Image of a filled select with a different theme applied"
|
||||
>
|
||||
<style>
|
||||
.styled-example.filled {
|
||||
--md-filled-select-text-field-container-shape: 0px;
|
||||
--md-filled-select-text-field-container-color: #f7faf9;
|
||||
--md-filled-field-content-color: #005353;
|
||||
--md-filled-field-content-font: system-ui;
|
||||
}
|
||||
.styled-example.filled md-filled-select::part(menu) {
|
||||
--md-menu-container-color: #f4fbfa;
|
||||
--md-menu-container-shape: 0px;
|
||||
--md-menu-item-container-color: transparent;
|
||||
}
|
||||
</style>
|
||||
<md-filled-select>
|
||||
<md-select-option selected value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="tomato" headline="Tomato"></md-select-option>
|
||||
</md-filled-select>
|
||||
</figure>
|
||||
</div>
|
||||
26
docs/components/figures/select/theming-outlined.html
Normal file
26
docs/components/figures/select/theming-outlined.html
Normal file
@ -0,0 +1,26 @@
|
||||
<div class="figure-wrapper">
|
||||
<figure
|
||||
class="styled-example outlined"
|
||||
title="Outlined select theming example"
|
||||
aria-label="Image of an outlined select with a different theme applied"
|
||||
>
|
||||
<style>
|
||||
.styled-example.outlined {
|
||||
--md-outlined-select-text-field-outline-color: #6e7979;
|
||||
--md-outlined-select-text-field-container-shape: 0px;
|
||||
--md-outlined-select-text-field-input-text-color: #005353;
|
||||
--md-outlined-select-text-field-input-text-font: system-ui;
|
||||
}
|
||||
.styled-example.outlined md-outlined-select::part(menu) {
|
||||
--md-menu-container-color: #f4fbfa;
|
||||
--md-menu-container-shape: 0px;
|
||||
--md-menu-item-container-color: transparent;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-outlined-select>
|
||||
<md-select-option selected value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="tomato" headline="Tomato"></md-select-option>
|
||||
</md-outlined-select>
|
||||
</figure>
|
||||
</div>
|
||||
27
docs/components/figures/select/usage.html
Normal file
27
docs/components/figures/select/usage.html
Normal file
@ -0,0 +1,27 @@
|
||||
<div class="figure-wrapper">
|
||||
<style>
|
||||
main > .figure-wrapper {
|
||||
/* prevent scrolling bars on dropdown menu open */
|
||||
overflow: visible;
|
||||
/* unset page styles */
|
||||
--md-list-item-container-shape: 0px;
|
||||
}
|
||||
</style>
|
||||
<figure
|
||||
style="justify-content: center; gap: 8px"
|
||||
title="Example usage of an outlined dropdown menu and a filled dropdown menu."
|
||||
aria-label="An outlined dropdown menu filled with Apple, and a filled dropdown menu."
|
||||
>
|
||||
<md-outlined-select>
|
||||
<md-select-option headline=""></md-select-option>
|
||||
<md-select-option selected value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="apricot" headline="Apricot"></md-select-option>
|
||||
</md-outlined-select>
|
||||
|
||||
<md-filled-select>
|
||||
<md-select-option headline=""></md-select-option>
|
||||
<md-select-option value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="apricot" headline="Apricot"></md-select-option>
|
||||
</md-filled-select>
|
||||
</figure>
|
||||
</div>
|
||||
BIN
docs/components/images/select/hero.png
Normal file
BIN
docs/components/images/select/hero.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
BIN
docs/components/images/select/theming-filled.png
Normal file
BIN
docs/components/images/select/theming-filled.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
BIN
docs/components/images/select/theming-outlined.png
Normal file
BIN
docs/components/images/select/theming-outlined.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
BIN
docs/components/images/select/usage.png
Normal file
BIN
docs/components/images/select/usage.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
192
docs/components/select.md
Normal file
192
docs/components/select.md
Normal file
@ -0,0 +1,192 @@
|
||||
<!-- catalog-only-start --><!-- ---
|
||||
name: Select
|
||||
dirname: select
|
||||
-----><!-- catalog-only-end -->
|
||||
|
||||
<catalog-component-header image-align="start">
|
||||
<catalog-component-header-title slot="title">
|
||||
|
||||
# Select
|
||||
|
||||
<!-- no-catalog-start -->
|
||||
|
||||
<!--*
|
||||
# Document freshness: For more information, see go/fresh-source.
|
||||
freshness: { owner: 'ajakubowicz' reviewed: '2023-09-14' }
|
||||
tag: 'docType:reference'
|
||||
*-->
|
||||
|
||||
<!-- go/md-select -->
|
||||
|
||||
<!-- [TOC] -->
|
||||
|
||||
<!-- external-only-start -->
|
||||
**This documentation is fully rendered on the
|
||||
[Material Web catalog](https://material-web.dev/components/<component>/)**
|
||||
<!-- external-only-end -->
|
||||
|
||||
<!-- no-catalog-end -->
|
||||
|
||||
[Select menus](https://m3.material.io/components/menus/overview#b1704de4-94b7-4177-9e96-b677ae767cb4)<!-- {.external} -->
|
||||
display a list of choices on temporary surfaces and display the currently
|
||||
selected menu item above the menu.
|
||||
|
||||
</catalog-component-header-title>
|
||||
|
||||
<img class="hero" src="images/select/hero.png" alt="A textfield containing the text Item 2, with a dropdown menu containing Item 1, Item 2, and Item 3.">
|
||||
|
||||
</catalog-component-header>
|
||||
|
||||
* Design article (*coming soon*)
|
||||
* API Documentation (*coming soon*)
|
||||
* [Source code](https://github.com/material-components/material-web/tree/main/select)
|
||||
<!-- {.external} -->
|
||||
|
||||
## Usage
|
||||
|
||||
Select (also referred to as a dropdown menu) allows choosing a value from a
|
||||
fixed list of available options. It is analogous to the native HTML
|
||||
[`<select>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select)<!-- {.external} -->.
|
||||
|
||||
<!-- no-catalog-start -->
|
||||
|
||||
|
||||
|
||||
<!-- no-catalog-end -->
|
||||
<!-- catalog-include "figures/select/usage.html" -->
|
||||
|
||||
```html
|
||||
<md-outlined-select>
|
||||
<md-select-option headline=""></md-select-option>
|
||||
<md-select-option selected value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="apricot" headline="Apricot"></md-select-option>
|
||||
</md-outlined-select>
|
||||
|
||||
<md-filled-select>
|
||||
<md-select-option headline=""></md-select-option>
|
||||
<md-select-option value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="apricot" headline="Apricot"></md-select-option>
|
||||
</md-filled-select>
|
||||
```
|
||||
|
||||
### Required select
|
||||
|
||||
Indicate that a selection is mandatory by adding the `required` attribute.
|
||||
|
||||
```html
|
||||
<md-filled-select required>
|
||||
<md-select-option value="one" headline="One"></md-select-option>
|
||||
<md-select-option value="two" headline="Two"></md-select-option>
|
||||
</md-filled-select>
|
||||
```
|
||||
|
||||
<!--
|
||||
## Accessibility
|
||||
|
||||
*Insert a 1-2 sentence description of a common accessibility scenario, followed
|
||||
by a code snippet. Do not include a rendered image for accessibility examples.*
|
||||
|
||||
```html
|
||||
<component-name aria-label="Example">
|
||||
```
|
||||
|
||||
*Repeat with additional examples as needed to explain how to make the component
|
||||
accessible.* -->
|
||||
|
||||
## Theming
|
||||
|
||||
Select supports
|
||||
[Material theming](https://github.com/material-components/material-web/blob/main/docs/theming/README.md)<!-- {.external} -->
|
||||
and can be customized in terms of color, typography, and shape.
|
||||
|
||||
### Filled Select tokens
|
||||
|
||||
Token | Default value
|
||||
----------------------------------------------- | -------------
|
||||
`--md-filled-select-text-field-container-color` | `--md-sys-color-surface-container-highest`
|
||||
`--md-filled-select-text-field-container-shape` | `4px`
|
||||
`--md-filled-field-content-color` | `--md-sys-color-on-surface`
|
||||
`--md-filled-field-content-font` | `--md-sys-typescale-body-large-font`
|
||||
|
||||
* [Filled Select tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-filled-select.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
To theme the select's dropdown menu, use the `md-menu` component tokens on the
|
||||
`::part(menu)` selector.
|
||||
|
||||
### Filled Select example
|
||||
|
||||
<!-- no-catalog-start -->
|
||||
|
||||
|
||||
|
||||
<!-- no-catalog-end -->
|
||||
<!-- catalog-include "figures/select/theming-filled.html" -->
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-filled-select-text-field-container-shape: 0px;
|
||||
--md-filled-select-text-field-container-color: #f7faf9;
|
||||
--md-filled-field-content-color: #005353;
|
||||
--md-filled-field-content-font: system-ui;
|
||||
}
|
||||
|
||||
md-filled-select::part(menu) {
|
||||
--md-menu-container-color: #f4fbfa;
|
||||
--md-menu-container-shape: 0px;
|
||||
--md-menu-item-container-color: transparent;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-filled-select>
|
||||
<md-select-option selected value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="tomato" headline="Tomato"></md-select-option>
|
||||
</md-filled-select>
|
||||
```
|
||||
|
||||
### Outlined Select tokens
|
||||
|
||||
Token | Default value
|
||||
-------------------------------------------------- | -------------
|
||||
`--md-outlined-select-text-field-outline-color` | `--md-sys-color-outline`
|
||||
`--md-outlined-select-text-field-container-shape` | `4px`
|
||||
`--md-outlined-select-text-field-input-text-color` | `--md-sys-color-on-surface`
|
||||
`--md-outlined-select-text-field-input-text-font` | `--md-sys-typescale-body-large-font`
|
||||
|
||||
* [Outlined Select tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-outlined-select.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Outlined Select example
|
||||
|
||||
<!-- no-catalog-start -->
|
||||
|
||||
|
||||
|
||||
<!-- no-catalog-end -->
|
||||
<!-- catalog-include "figures/select/theming-outlined.html" -->
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-outlined-select-text-field-outline-color: #6e7979;
|
||||
--md-outlined-select-text-field-container-shape: 0px;
|
||||
--md-outlined-select-text-field-input-text-color: #005353;
|
||||
--md-outlined-select-text-field-input-text-font: system-ui;
|
||||
}
|
||||
|
||||
md-outlined-select::part(menu) {
|
||||
--md-menu-container-color: #f4fbfa;
|
||||
--md-menu-container-shape: 0px;
|
||||
--md-menu-item-container-color: transparent;
|
||||
}
|
||||
</style>
|
||||
|
||||
<md-outlined-select>
|
||||
<md-select-option selected value="apple" headline="Apple"></md-select-option>
|
||||
<md-select-option value="tomato" headline="Tomato"></md-select-option>
|
||||
</md-outlined-select>
|
||||
```
|
||||
|
||||
<!-- auto-generated API docs start -->
|
||||
<!-- auto-generated API docs end -->
|
||||
Loading…
x
Reference in New Issue
Block a user