Skip to content

Latest commit

 

History

History
174 lines (121 loc) · 4.83 KB

focus-ring.md

File metadata and controls

174 lines (121 loc) · 4.83 KB

Focus ring

Focus rings are accessible outlines for components to show keyboard focus.

Focus rings follow the same heuristics as :focus-visible to determine when they are visible.

Three elements with a focus ring that moves between them.

Usage

Focus rings display on keyboard navigation. They may be attached to a control in one of three ways.

An element with a focus ring.

  1. Attached to the parent element

    <button style="position: relative">
      <md-focus-ring style="--md-focus-ring-shape: 8px"></md-focus-ring>
    </button>
  2. Attached to a referenced element

    <div style="position: relative">
      <md-focus-ring for="control" style="--md-focus-ring-shape: 8px"></md-focus-ring>
      <input id="control">
    </div>
  3. Attached imperatively

    <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.

An element with a focus ring that animates inward.

<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.

An element with a focus ring that does not animate.

<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 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

Example

Image of a focus ring with a different theme applied

<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>

API

MdFocusRing <md-focus-ring>

Properties

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

Methods

Method Parameters Returns Description
attach control void
detach None void

Events

Event Type Bubbles Composed Description
visibility-changed Event No No Fired whenever visible changes.