A reusable focus directive for reusable Vue.js components
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dist Release 2.1.0 Nov 14, 2016
examples Add `.lazy` modifier to the docs and example Nov 14, 2016
.eslintrc Draft Dec 20, 2015
.gitignore Initial commit Dec 19, 2015
CHANGELOG.md Release 2.1.0 Nov 14, 2016
LICENSE Draft Dec 20, 2015
README.md Update demo link to v2 Feb 22, 2017
build.js Screw ie8 during minification Dec 25, 2015
index.js Release 2.1.0 Nov 14, 2016
package.json Release 2.1.0 Nov 14, 2016

README.md

vue-focus

A reusable focus directive for reusable Vue.js components

npm version

Overview

It can be tricky to manage input focus. You always have to fall back to accessing DOM elements and calling .focus or .blur on them.

Well not anymore. vue-focus lets you manage focus from the safety of your view model.

Check out the examples, read the docs or file an issue.

Use cases

  • Focus the field when the modal windows appears
  • Track the focus to show a hint for the focused field
  • Move between fields with cursor keys
  • Implement custom focus-related controls (e.g labels)

Requirements

  • vue: ^2.0.0

If you need a version for Vue 1, try vue-focus@1.0.

Install

From npm:

$ npm install vue-focus --save

From CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/vue-focus/2.1.0/vue-focus.js"></script>
<!-- OR -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/vue-focus/2.1.0/vue-focus.min.js"></script>

API

focus

A directive that binds focus to the expression in a one-way manner, so that the element receives focus when the expression is truthy and loses focus when the expression is falsy.

import { focus } from 'vue-focus';

export default {
  directives: { focus: focus },
  template: '<input type="text" v-focus="focused" @focus="focused = true" @blur="focused = false">',
  data: function() {
    return {
      focused: false,
    };
  },
};

NOTE: As opposed to 1.x, in Vue 2.0, directives are updated every time the host component rerenders, not just when the directive expression chages. Somethimes this may be undesirable, especially for the "autofocus" use case. If you want to mimic the 1.x behavior, then add the .lazy modifier to the directive, e.g. v-focus.lazy="true".

mixin

A mixin that makes the v-focus directive available to the component under the default name.

import { mixin as focusMixin }  from 'vue-focus';

export default {
  mixins: [ focusMixin ],
  template: '<input type="text" v-focus="focused" @focus="focused = true" @blur="focused = false">',
  data: function() {
    return {
      focused: false,
    };
  },
};

Caveats

  1. Although you can write an input that gains focus immediately after loosing it, this is not recommended, as two such inputs will fall into infinite recursion and freeze the browser.

Notes

Form elements are not the only elements that are able to receive focus. The list also includes links, elements with tabindex attribute set and elements with contentEditable set to true.

License

MIT