@q42/floating-focus-a11y

Accessible Floating Focus

A clear, beautiful and easy to implement focus-state solution that improves accessibility in an aesthetically pleasing way.

Installation

With npm installed, run

$ npm install @q42/floating-focus-a11y --save

Usage

Import the package and instantiate the class on page load:

import FloatingFocus from '@q42/floating-focus-a11y';
new FloatingFocus(containerElement); // Element is an optional parameter which defaults to `document.body`

Define a default outline and outline-offset. Either of these values can be overruled per component:

/* Hide all default focus states if a mouse is used, this is completely optional ofcourse */
*:focus {
  outline: none;
}

/* Default outline value, which will be applied to all elements receiving focus, this is a required step. */
/* The .focus class is used by the focus target, more below. */
.floating-focus-enabled :focus, .floating-focus-enabled .focus {
  outline: dodgerblue solid 2px;
  outline-offset: 8px;
}

/* Give all buttons a green focus state instead of dodgerblue, this is optional in case it's needed. */
.floating-focus-enabled [type="button"]:focus {
  outline-color: green;
  outline-offset: 4px;
}

Focus target

Sometimes the actual element that receives focus is hidden from view, as is common with a custom input field. In this case it's possible to define a focus-target attribute on the focusable element.

<input type="file" class="hidden" id="file-upload-123" focus-target="file-upload-123-label"/>
<label id="file-upload-123-label" for="file-upload-123">Please upload a file</label>

This will append the focus class to the target element and make the visual focus box appear around the target element, instead of the element that actually has the native focus.

Separate stylesheet

For convenience, the styles are included in the script by default. There is also an option to include the stylesheet separately. This is particularly useful with strict style-src 'self' CORS headers.

Import unstyled dist file:

import FloatingFocus from '@q42/floating-focus-a11y/dist/unstyled';

The stylesheet can then be separately imported with your favorite CSS preprocessor:

@import '@q42/floating-focus-a11y/dist/unstyled';

Develop

$ npm run build
$ npm run watch
$ npm run test

Deploy

# bump version
$ npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

# publish
$ npm publish

License

MIT