mirror of
https://github.com/thejakubruzicka/MNotes.git
synced 2025-07-10 14:34:05 +02:00
175 lines
4.8 KiB
Markdown
175 lines
4.8 KiB
Markdown
|
# Focus ring
|
||
|
|
||
|
<!--*
|
||
|
# Document freshness: For more information, see go/fresh-source.
|
||
|
freshness: { owner: 'lizmitchell' reviewed: '2025-05-20' }
|
||
|
tag: 'docType:reference'
|
||
|
*-->
|
||
|
|
||
|
<!-- go/md-focus-ring -->
|
||
|
|
||
|
<!-- [TOC] -->
|
||
|
|
||
|
Focus rings are accessible outlines for components to show keyboard focus.
|
||
|
|
||
|
Focus rings follow the same heuristics as
|
||
|
[`:focus-visible`](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible)<!-- {.external} -->
|
||
|
to determine when they are visible.
|
||
|
|
||
|

|
||
|
|
||
|
* [API Documentation](#api)
|
||
|
* [Source code](https://github.com/material-components/material-web/tree/main/focus)
|
||
|
<!-- {.external} -->
|
||
|
|
||
|
## Usage
|
||
|
|
||
|
Focus rings display on keyboard navigation. They may be attached to a control in
|
||
|
one of three ways.
|
||
|
|
||
|

|
||
|
|
||
|
1. Attached to the parent element
|
||
|
|
||
|
```html
|
||
|
<button style="position: relative">
|
||
|
<md-focus-ring style="--md-focus-ring-shape: 8px"></md-focus-ring>
|
||
|
</button>
|
||
|
```
|
||
|
|
||
|
1. Attached to a referenced element
|
||
|
|
||
|
```html
|
||
|
<div style="position: relative">
|
||
|
<md-focus-ring for="control" style="--md-focus-ring-shape: 8px"></md-focus-ring>
|
||
|
<input id="control">
|
||
|
</div>
|
||
|
```
|
||
|
|
||
|
1. Attached imperatively
|
||
|
|
||
|
```html
|
||
|
<div style="position: relative">
|
||
|
<md-focus-ring id="ring" style="--md-focus-ring-shape: 8px"></md-focus-ring>
|
||
|
<button id="ring-control"></button>
|
||
|
</div>
|
||
|
<script>
|
||
|
const focusRing = document.querySelector('#ring');
|
||
|
const control = document.querySelector('#ring-control');
|
||
|
focusRing.attach(control);
|
||
|
</script>
|
||
|
```
|
||
|
|
||
|
> Note: focus rings must be placed within a `position: relative` container.
|
||
|
|
||
|
### Inward
|
||
|
|
||
|
Focus rings can be changed to animate inwards by adding an `inward` attribute.
|
||
|
This is useful for components like list items.
|
||
|
|
||
|

|
||
|
|
||
|
```html
|
||
|
<button style="position: relative">
|
||
|
<md-focus-ring inward style="--md-focus-ring-shape: 8px"></md-focus-ring>
|
||
|
</button>
|
||
|
```
|
||
|
|
||
|
### Animation
|
||
|
|
||
|
The focus ring animation may be customized or disabled using CSS custom
|
||
|
properties.
|
||
|
|
||
|

|
||
|
|
||
|
```html
|
||
|
<style>
|
||
|
md-focus-ring {
|
||
|
--md-focus-ring-duration: 0s; /* disabled animation */
|
||
|
}
|
||
|
</style>
|
||
|
```
|
||
|
|
||
|
## Accessibility
|
||
|
|
||
|
Focus rings are visual components and do not have assistive technology
|
||
|
requirements.
|
||
|
|
||
|
## Theming
|
||
|
|
||
|
Focus rings supports [Material theming](../theming/README.md) and can be
|
||
|
customized in terms of color and shape.
|
||
|
|
||
|
### Tokens
|
||
|
|
||
|
Token | Default value
|
||
|
----------------------- | --------------------------
|
||
|
`--md-focus-ring-color` | `--md-sys-color-secondary`
|
||
|
`--md-focus-ring-shape` | `--md-sys-shape-corner-full`
|
||
|
`--md-focus-ring-width` | `3px`
|
||
|
|
||
|
* [All tokens](https://github.com/material-components/material-web/blob/main/tokens/_md-comp-focus-ring.scss)
|
||
|
<!-- {.external} -->
|
||
|
|
||
|
### Example
|
||
|
|
||
|

|
||
|
|
||
|
```html
|
||
|
<style>
|
||
|
md-focus-ring {
|
||
|
--md-focus-ring-shape: 0px;
|
||
|
--md-focus-ring-width: 2px;
|
||
|
--md-focus-ring-active-width: 4px;
|
||
|
--md-sys-color-secondary: #4A6363;
|
||
|
}
|
||
|
</style>
|
||
|
|
||
|
<button>
|
||
|
<md-focus-ring></md-focus-ring>
|
||
|
</button>
|
||
|
```
|
||
|
|
||
|
<!-- auto-generated API docs start -->
|
||
|
|
||
|
## API
|
||
|
|
||
|
|
||
|
### MdFocusRing <code><md-focus-ring></code>
|
||
|
|
||
|
#### Properties
|
||
|
|
||
|
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
| Property | Attribute | Type | Default | Description |
|
||
|
| --- | --- | --- | --- | --- |
|
||
|
| `visible` | `visible` | `boolean` | `false` | Makes the focus ring visible. |
|
||
|
| `inward` | `inward` | `boolean` | `false` | Makes the focus ring animate inwards instead of outwards. |
|
||
|
| `htmlFor` | | `string` | `undefined` | |
|
||
|
| `control` | | `HTMLElement` | `undefined` | |
|
||
|
|
||
|
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
#### Methods
|
||
|
|
||
|
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
| Method | Parameters | Returns | Description |
|
||
|
| --- | --- | --- | --- |
|
||
|
| `attach` | `control` | `void` | |
|
||
|
| `detach` | _None_ | `void` | |
|
||
|
|
||
|
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
#### Events
|
||
|
|
||
|
<!-- mdformat off(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
| Event | Type | [Bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles) | [Composed](https://developer.mozilla.org/en-US/docs/Web/API/Event/composed) | Description |
|
||
|
| --- | --- | --- | --- | --- |
|
||
|
| `visibility-changed` | `Event` | No | No | Fired whenever `visible` changes. |
|
||
|
|
||
|
<!-- mdformat on(autogenerated might break rendering in catalog) -->
|
||
|
|
||
|
<!-- auto-generated API docs end -->
|