mirror of
https://github.com/material-components/material-web.git
synced 2024-09-21 10:38:19 +03:00
docs: add ripple docs
PiperOrigin-RevId: 537996359
This commit is contained in:
parent
3d7612e761
commit
d4d10ee9e6
BIN
docs/components/images/ripple/hero.gif
Normal file
BIN
docs/components/images/ripple/hero.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 170 KiB |
BIN
docs/components/images/ripple/theming.gif
Normal file
BIN
docs/components/images/ripple/theming.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 62 KiB |
BIN
docs/components/images/ripple/usage-unbounded.gif
Normal file
BIN
docs/components/images/ripple/usage-unbounded.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 81 KiB |
BIN
docs/components/images/ripple/usage.gif
Normal file
BIN
docs/components/images/ripple/usage.gif
Normal file
Binary file not shown.
After Width: | Height: | Size: 59 KiB |
258
docs/components/ripple.md
Normal file
258
docs/components/ripple.md
Normal file
@ -0,0 +1,258 @@
|
||||
<!-- catalog-only-start --><!-- ---
|
||||
name: Ripple
|
||||
dirname: ripple
|
||||
-----><!-- catalog-only-end -->
|
||||
|
||||
<catalog-component-header image-align="start">
|
||||
<catalog-component-header-title slot="title">
|
||||
|
||||
# Ripple
|
||||
|
||||
<!--*
|
||||
# Document freshness: For more information, see go/fresh-source.
|
||||
freshness: { owner: 'lizmitchell' reviewed: '2023-06-05' }
|
||||
tag: 'docType:reference'
|
||||
*-->
|
||||
|
||||
<!-- github-only-start -->
|
||||
|
||||
<!-- go/md-ripple -->
|
||||
|
||||
<!-- [TOC] -->
|
||||
|
||||
TODO: update link to live site
|
||||
|
||||
**This documentation is fully rendered on the
|
||||
[Material Web catalog](https://github.com/material-components/material-web/tree/main)<!-- {.external} -->**
|
||||
|
||||
<!-- github-only-end -->
|
||||
|
||||
Ripples are
|
||||
[state layers](https://m3.material.io/foundations/interaction/states/state-layers)<!-- {.external} -->
|
||||
used to communicate the status of a component or interactive element.
|
||||
|
||||
A state layer is a semi-transparent covering on an element that indicates its
|
||||
state. A layer can be applied to an entire element or in a circular shape.
|
||||
|
||||
</catalog-component-header-title>
|
||||
|
||||
<img src="images/ripple/hero.gif" alt="Two containers that display a bounded and unbounded ripple on interaction."
|
||||
title="A bounded and unbounded ripple.">
|
||||
|
||||
</catalog-component-header>
|
||||
|
||||
* [Design article](https://m3.material.io/foundations/interaction/states/state-layers)
|
||||
<!-- {.external} -->
|
||||
* API Documentation (*coming soon*)
|
||||
* [Source code](https://github.com/material-components/material-web/tree/main/ripple)
|
||||
<!-- {.external} -->
|
||||
|
||||
<!-- catalog-only-start -->
|
||||
|
||||
<!--
|
||||
|
||||
## Interactive Demo
|
||||
|
||||
{% playgroundexample dirname=dirname %}
|
||||
|
||||
-->
|
||||
|
||||
<!-- catalog-only-end -->
|
||||
|
||||
## Usage
|
||||
|
||||
Ripples display on hover and press pointer interactions. They may be attached to
|
||||
a control in one of three ways.
|
||||
|
||||
<!-- github-only-start -->
|
||||
|
||||
![A container that displays a bounded ripple on interaction.](images/ripple/usage.gif "A bounded ripple.")
|
||||
|
||||
<!-- github-only-end -->
|
||||
<!-- catalog-only-start -->
|
||||
|
||||
<!--
|
||||
|
||||
<div class="figure-wrapper">
|
||||
<figure
|
||||
title="A bounded ripple."
|
||||
aria-label="A container that displays a bounded ripple on interaction.">
|
||||
TODO: update figure
|
||||
</figure>
|
||||
</div>
|
||||
|
||||
-->
|
||||
|
||||
<!-- catalog-only-end -->
|
||||
|
||||
1. Attached to the parent element
|
||||
|
||||
```html
|
||||
<style>
|
||||
.container {
|
||||
position: relative;
|
||||
}
|
||||
</style>
|
||||
<button class="container">
|
||||
<md-ripple></md-ripple>
|
||||
</button>
|
||||
```
|
||||
|
||||
1. Attached to a referenced element
|
||||
|
||||
```html
|
||||
<style>
|
||||
.container {
|
||||
position: relative;
|
||||
}
|
||||
</style>
|
||||
<div class="container">
|
||||
<md-ripple for="control"></md-ripple>
|
||||
<input id="control">
|
||||
</div>
|
||||
```
|
||||
|
||||
1. Attached imperatively
|
||||
|
||||
```html
|
||||
<style>
|
||||
.container {
|
||||
position: relative;
|
||||
}
|
||||
</style>
|
||||
<div class="container">
|
||||
<md-ripple id="ripple"></md-ripple>
|
||||
<button id="ripple-control"></button>
|
||||
</div>
|
||||
<script>
|
||||
const ripple = document.querySelector('#ripple');
|
||||
const control = document.querySelector('#ripple-control');
|
||||
ripple.attach(control);
|
||||
</script>
|
||||
```
|
||||
|
||||
> Note: ripples must be placed within a `position: relative` container.
|
||||
|
||||
### Unbounded
|
||||
|
||||
To create an unbounded circular ripple centered on an element, use the following styles.
|
||||
|
||||
```css
|
||||
.container {
|
||||
display: grid;
|
||||
place-items: center;
|
||||
position: relative;
|
||||
}
|
||||
|
||||
md-ripple.unbounded {
|
||||
border-radius: 50%;
|
||||
inset: unset;
|
||||
height: var(--state-layer-size);
|
||||
width: var(--state-layer-size);
|
||||
}
|
||||
```
|
||||
|
||||
<!-- github-only-start -->
|
||||
|
||||
![A circular container with an inner circle that displays an unbounded ripple around it on interaction.](images/ripple/usage-unbounded.gif "An unbounded ripple.")
|
||||
|
||||
<!-- github-only-end -->
|
||||
<!-- catalog-only-start -->
|
||||
|
||||
<!--
|
||||
|
||||
<div class="figure-wrapper">
|
||||
<figure
|
||||
title="An unbounded ripple."
|
||||
aria-label="A circular container with an inner circle that displays an unbounded ripple around it on interaction.">
|
||||
TODO: update figure
|
||||
</figure>
|
||||
</div>
|
||||
|
||||
-->
|
||||
|
||||
<!-- catalog-only-end -->
|
||||
|
||||
```html
|
||||
<style>
|
||||
.container {
|
||||
border-radius: 50%;
|
||||
height: 32px;
|
||||
width: 32px;
|
||||
|
||||
/* Needed for unbounded ripple */
|
||||
display: grid;
|
||||
place-items: center;
|
||||
position: relative;
|
||||
}
|
||||
|
||||
md-ripple.unbounded {
|
||||
/* Needed for unbounded ripple */
|
||||
border-radius: 50%;
|
||||
inset: unset;
|
||||
height: 64px;
|
||||
width: 64px;
|
||||
}
|
||||
</style>
|
||||
<button class="container">
|
||||
<md-ripple class="unbounded"></md-ripple>
|
||||
</button>
|
||||
```
|
||||
|
||||
## Accessibility
|
||||
|
||||
Ripples are visual components and do not have assistive technology requirements.
|
||||
|
||||
## Theming
|
||||
|
||||
Ripples support [Material theming](../theming.md) and can be customized in terms
|
||||
of color.
|
||||
|
||||
### Tokens
|
||||
|
||||
Token | Default value
|
||||
------------------------ | ------------------------
|
||||
`--md-ripple-hover-color` | `--md-sys-color-on-surface`
|
||||
`--md-ripple-pressed-color` | `--md-sys-color-on-surface`
|
||||
|
||||
* [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-ripple.scss)
|
||||
<!-- {.external} -->
|
||||
|
||||
### Example
|
||||
|
||||
<!-- github-only-start -->
|
||||
|
||||
![Image of a ripple with a different theme applied](images/ripple/theming.gif "Ripple theming example.")
|
||||
|
||||
<!-- github-only-end -->
|
||||
<!-- catalog-only-start -->
|
||||
|
||||
<!--
|
||||
|
||||
<div class="figure-wrapper">
|
||||
<figure
|
||||
class="styled-example"
|
||||
title="Ripple theming example."
|
||||
aria-label="Image of a ripple with a different theme applied">
|
||||
TODO: update figure
|
||||
</figure>
|
||||
</div>
|
||||
|
||||
-->
|
||||
|
||||
```html
|
||||
<style>
|
||||
:root {
|
||||
--md-sys-color-primary: #006A6A;
|
||||
--md-ripple-hover-color: var(--md-sys-color-primary);
|
||||
--md-ripple-pressed-color: var(--md-sys-color-primary);
|
||||
}
|
||||
|
||||
.container {
|
||||
position: relative;
|
||||
}
|
||||
</style>
|
||||
<button class="container">
|
||||
<md-ripple></md-ripple>
|
||||
</button>
|
||||
```
|
Loading…
Reference in New Issue
Block a user