Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/posva/focus-trap-vue
Vue component to trap the focus within a DOM element
https://github.com/posva/focus-trap-vue
a11y focus lock trap ui ux vue
Last synced: 3 months ago
JSON representation
Vue component to trap the focus within a DOM element
- Host: GitHub
- URL: https://github.com/posva/focus-trap-vue
- Owner: posva
- License: mit
- Created: 2019-07-30T11:47:56.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-03-25T04:09:06.000Z (3 months ago)
- Last Synced: 2024-03-25T05:23:36.176Z (3 months ago)
- Topics: a11y, focus, lock, trap, ui, ux, vue
- Language: JavaScript
- Homepage: https://focus-trap-vue.esm.dev
- Size: 2.39 MB
- Stars: 199
- Watchers: 4
- Forks: 20
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
Lists
- awesome-access - focus-trap-vue - Vue component to trap the focus within a DOM element. (Components and plugins / Courses)
README
# focus-trap-vue [](https://circleci.com/gh/posva/focus-trap-vue) [](https://www.npmjs.com/package/focus-trap-vue) [](https://github.com/posva/thanks)
> Vue component to trap the focus within a DOM element
## Installation
### For Vue 2
```sh
npm install focus-trap focus-trap-vue@legacy
```
### For Vue 3
```sh
npm install focus-trap focus-trap-vue
```
## Usage
This library exports one single named export `FocusTrap` and **requires
[`focus-trap`](https://github.com/focus-trap/focus-trap) as a peer
dependency**. So you can locally import the component or declare it globally:
### Register globally in a Vue 2 app
```js
import { FocusTrap } from 'focus-trap-vue'
Vue.component('FocusTrap', FocusTrap)
```
### Register globally in a Vue 3 app
```js
import { FocusTrap } from 'focus-trap-vue'
createApp(App)
.component('FocusTrap', FocusTrap)
.mount('#app')
```
**Note this documentation is for Vue 3 and some props/events might not exist in the Vue 2 version**
`FocusTrap` can be controlled in three different ways:
- by using the `active` _Boolean_ prop
- by using `v-model:active` (uses the `active` prop, _Vue 3 only_)
- by calling the `activate`/`deactivate` method on the component
The recommended approach is using `v-model:active` and it should contain **one single child**:
```html
Do you accept the cookies?
Yes
No
```
When `isActive` becomes `true`, it activates the focus trap. By default it sets
the focus to its child, so make sure the element is a focusable element. If it's
not you wil need to give it the `tabindex="-1"` attribute. You can also
customize the initial element focused. This element should be an element that
the user can interact with. For example, an input. It's a good practice to
always focus an interactable element instead of the modal container:
```html
What name do you want to use?
New Name
Change name
```
### Props
`FocusTrap` also accepts other props:
- `escapeDeactivates`: `boolean`
- `returnFocusOnDeactivate`: `boolean`
- `allowOutsideClick`: `boolean | ((e: MouseEvent | TouchEvent) => boolean)`
- `clickOutsideDeactivates`: `boolean | ((e: MouseEvent | TouchEvent) => boolean)`
- `initialFocus`: `string | (() => Element)` _Selector or function returning an Element_
- `fallbackFocus`: `string | (() => Element)` _Selector or function returning an Element_
- `delayInitialFocus`: `boolean`
- `tabbableOptions`: `FocusTrapTabbableOptions` _Options passed to `tabbableOptions`_
Please, refer to
[focus-trap](https://github.com/focus-trap/focus-trap#focustrap--createfocustrapelement-createoptions)
documentation to know what they do.
### Events
`FocusTrap` emits 2 events. They are in-sync with the prop `active`
- `activate`: Whenever the trap activates
- `deactivate`: Whenever the trap deactivates (note it can also be deactivated by
pressing Esc or clicking outside)
### Methods
`FocusTrap` can be used without `v-model:active`. In that case, you will use the
methods and _probably_ need to initialize the trap as _deactivated_, otherwise,
the focus will start as active:
```html
$refs.focusTrap.activate()">Show the modal
Hello there!
$refs.focusTrap.deactivate()">Okay...
```
Note the use of arrow functions, this is necessary because we are accessing
`$refs` which are unset on first render.
## Related
- Focus Trap: https://github.com/focus-trap/focus-trap
## License
[MIT](http://opensource.org/licenses/MIT)