https://github.com/undecaf/vue-autofocus
A smart Vue autofocus directive
https://github.com/undecaf/vue-autofocus
autofocus directive vue vue-autofocus
Last synced: about 1 month ago
JSON representation
A smart Vue autofocus directive
- Host: GitHub
- URL: https://github.com/undecaf/vue-autofocus
- Owner: undecaf
- License: mit
- Created: 2020-08-20T20:52:00.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2020-09-12T20:24:36.000Z (over 5 years ago)
- Last Synced: 2025-09-20T05:26:21.077Z (9 months ago)
- Topics: autofocus, directive, vue, vue-autofocus
- Language: JavaScript
- Homepage:
- Size: 2.21 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# A smart Vue autofocus directive
This directive, `v-autofocus`, tries to be smart in the following ways:
+ When placed on a non-focusable element (such as a `
`) or a Vue component,
it will focus on the first focusable descendant. Descendants are scanned in document order.
+ It can focus on `contenteditable` elements, too.
+ Focusable candidates [can be further restricted by a CSS selector](#configuration).
+ This allows `v-autofocus` to work with opaque Vue input components such as the
[Vue Material Datepicker](https://vuematerial.io/components/datepicker),
[Vue Material Chips](https://vuematerial.io/components/datepicker) and
[Vue Material Autocomplete](https://vuematerial.io/components/autocomplete).
+ `v-autofocus` can act [with some delay](#configuration) in order to be compatible with container components
that manipulate the focus _after_ their children have been inserted (e.g. the
[Vue Material Dialog](https://vuematerial.io/components/dialog)),
+ The focus can also be set [in response to child events](#configuration), e.g. when a dialog is
(re-)opened.
+ The directive [can be disabled](#configuration).
A simple online example [is available here](https://undecaf.github.io/vue-autofocus/example/)
([example source code](https://github.com/undecaf/vue-autofocus/blob/master/src/components/Demo.vue)).
Please note: in this context, an element is considered "focusable" if it can become the
[`document.activeElement`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/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](https://html.spec.whatwg.org/multipage/interaction.html#the-tabindex-attribute).
## Installation
As a module:
```shell script
$ npm install @undecaf/vue-autofocus
or
$ yarn add @undecaf/vue-autofocus
```
Included as ``:
```html
<script src="https://cdn.jsdelivr.net/npm/@undecaf/vue-autofocus/dist/directives.min.js">
```
## Usage
### Registering the directive
```javascript 1.8
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` | 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'`](https://twitter.com/DamianDulisz/status/981549658571968512) or
[`'md-opened'`](https://vuematerial.io/components/dialog)).
### Examples
A simple use case:
```html
```
Conditional autofocus:
```html
```
Focusing on the first focusable descendant:
```html
```
Focusing on the first focusable descendant that matches a selector:
```html
```
Auto-focusing on the input inside a [Vue Material Datepicker](https://vuematerial.io/components/datepicker):
```html
```
Setting the focus on the first input of a [Vue Material Dialog](https://vuematerial.io/components/dialog)
whenever the dialog is (re-)opened (a selector is required since the dialog container is
focusable):
```html
...
```
This will have no effect whatsoever:
```html
```
## License
Software: [MIT](http://opensource.org/licenses/MIT)
Documentation: [CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)