@undecaf/vue-autofocus

0.4.3 • Public • Published

A smart Vue autofocus directive

Minified size Open issues Vulnerabilities Total downloads License

This directive, v-autofocus, tries to be smart in the following ways:

A simple example is available here (example source code).

Please note: in this context, an element is considered "focusable" if it can become the document.activeElement. This includes contenteditable elements.

Focusable elements become non-focusable only if hidden or having attribute disabled. Elements with any integer tabindex are at least click focusable.

Installation

As a module:

$ npm install @undecaf/vue-autofocus
    or
$ yarn add @undecaf/vue-autofocus

Included as <script>:

<script src="https://cdn.jsdelivr.net/npm/@undecaf/vue-autofocus/dist/directives.min.js"></script>

Usage

Registering the directive

import autofocus from 'vue-autofocus'

Vue.use(autofocus)

Configuration

v-autofocus expects a configuration object, a primitive value as a single option (see below), or no value at all. Unspecified options get default values.

The configuration object supports the following properties:

Name Type Description Default
enabled Boolean Enables the directive if truthy. true
selector String Only an element matching this selector can receive the focus, starting with the element on which this directive is placed. '*'
on String or Array<String> Child event(s) that re-trigger auto-focusing. []
delay Number Delay (in ms) until the focus is set.
A value of 0 sets the focus synchronously with the trigger event.
50

If a value is specified that is not an object then its type determines which option it applies to: Boolean → enabled, String → selector, Array → on, Number → delay.

The configuration can be modified after binding; changes to on take effect immediately, all other changes become noticeable only after a child event (e.g. 'hook:updated' or 'md-opened').

Examples

A simple use case:

<input type="text" v-autofocus>

Conditional autofocus:

<input type="text" v-autofocus="{ enabled: active }">  <!-- or: autofocus="Boolean(active)" -->

Focusing on the first focusable descendant:

<div v-autofocus>
  <!-- These are not focusable -->
  <div><span>Not focusable</span></div>
  <img src="#">
  <a></a>
  <input type="hidden">
  <input type="text" disabled>

  <div>
    <!-- First focusable descendant -->
    <textarea v-model="comment"></textarea>
  </div>    
</div>

Focusing on the first focusable descendant that matches a selector:

<div autofocus="{ selector: '.focus-me' }">  <!-- or:  v-autofocus="'.focus-me'" -->
  <!-- Focusable but will not receive focus -->
  <textarea v-model="comment"></textarea>
    
  <!-- Will receive focus -->
  <input type="text" class="focus-me" v-model="text">
</div>

Auto-focusing on the input inside a Vue Material Datepicker:

<md-datepicker v-autofocus v-model="birthdate" :md-open-on-focus="false" />

Setting the focus on the first input of a Vue Material Dialog whenever the dialog is (re-)opened (a selector is required since the dialog container is focusable):

<md-dialog v-autofocus="{ selector: 'input', on: 'md-opened' }" :md-active="showDialog">
  ...
</md-dialog>

This will have no effect whatsoever:

<div v-autofocus>
  <input type="hidden">
</div>

License

Software: MIT

Documentation: CC-BY-SA 4.0

Package Sidebar

Install

npm i @undecaf/vue-autofocus

Weekly Downloads

0

Version

0.4.3

License

MIT

Unpacked Size

41.1 kB

Total Files

9

Last publish

Collaborators

  • undecaf