Vue.js component for accessible modals.
- 📟 fully accessible to screen readers;
- ⌨️ supports keyboard navigation;
- 🎯 focus trap;
- restores focus when modal is closed;
- simple API.
npm install vue-accessible-modal --saveyarn add vue-accessible-modalIt must be called before new Vue().
import Vue from 'vue'
import VueAccessibleModal from 'vue-accessible-modal'
// optional options
const options = {
transition: 'fade',
}
Vue.use(VueAccessibleModal, options)First off you should insert the <vue-accessible-modal /> component into your template, this is where your modals will be rendered:
<template>
<vue-accessible-modal />
</template>Then don't forget to include core styles:
SASS:
@import 'vue-accessible-modal/src/styles/core.scss';Or already compiled CSS:
CSS:
@import 'vue-accessible-modal/dist/index.css';
⚠️ Note that when you import already compiled CSS you don't have ability to overrideSASSvariables during build process, so it preferable to use.scssfile. But you still have ability to override default styles and change CSS custom properties during runtime.
There are SASS variables you can override during build process:
$v-modal-holder-padding: 32px !default;
$v-modal-backdrop-color: rgba(#333, 0.88) !default;
$v-modal-content-background-color: #fff !default;And CSS custom properties you can override during runtime:
:root {
--v-modal-holder-padding: #{$v-modal-holder-padding};
--v-modal-backdrop-color: #{$v-modal-backdrop-color};
--v-modal-content-background-color: #{$v-modal-content-background-color};
}🌈 The main purpose of the library is just to give you a simple wrapper over your modal components that makes them accessible and provide you with simple show/close API over them.
When you install the plugin it injects $modal property into each component during beforeCreate hook, so you can show or close modals through this.$modal.show or this.$modal.close methods appropriately.
⚠️ Note that your modal component should contain at least one focusable element to set focus on. There should be at least one button that closes the dialog<button @click="$modal.close()">Close dialog</button>.
$modal.show(component: VueComponent, options?: object) method accepts two arguments:
component: Vue.js component you want to display in the modal.options: object through which you can customize the behaviour of the modal.
options object can contain the following properties:
| Property | Description |
|---|---|
props |
props that will be passed to provided component via v-bind="props" |
listeners |
an object with listeners to listen to events emitted from passed component via v-on="listeners" |
classes |
custom classes that will be applied to the modal |
label |
value of aria-label attribute |
attributes |
any attribute you want to bind to the modal |
transition |
name of the transition that will be passed to transition component |
ℹ️ Note that through
options.attributesyou can bind any HTML attribute to a modal. For example if you want to bindaria-labelledbyoraria-describedby, you can do the following:
{
props: { },
listeners: { },
attributes: {
id: 'foo',
'aria-labelledby': 'foo',
'aria-describedby': 'bar',
},
}To close modal from anywhere in your app you should call this.$modal.close() method.
🆕 Support version 0.4.0
Since version 0.4.0 you can use vue-accessible-modal to confirm user actions.
this.$modal.confirm(component: VueComponent, message: string, options?: object) accepts tha same arguments as the $modal.show method, but the second argument is message (the value that will be passed to your component as message prop).
Your confirm component should accept three props: message , resolve and reject (since $modal.confirm leverages Promise).
Bellow is the example of usage of $modal.confirm:
ConfirmComponent.vue:
<template>
<section>
<h1>{{ message }}</h1>
<button type="button" @click="resolveHandler">Resolve</button>
<button type="button" @click="rejectHandler">Reject</button>
</section>
</template>import Vue from 'vue'
export default Vue.extend({
name: 'ConfirmComponent',
// required props
props: {
message: {
type: String,
required: true,
},
resolve: {
type: Function,
required: true,
},
reject: {
type: Function,
required: true,
},
},
methods: {
resolveHandler() {
// this value will be passed to `then`
this.resolve('foo')
},
rejectHandler() {
// this value will be passed to `catch`
this.reject('bar')
},
},
})import ConfirmComponent from 'path/to/confirm/component'
export default {
// ...
methods: {
confirm() {
this.$modal
.confirm(ConfirmComponent, 'Do you like JavaScript?')
.then(val => {
console.log(val)
})
.catch(val => {
console.log(val)
})
.finally(() => {
this.$modal.close()
})
},
},
// ...
}<vue-accessible-modal> component emits some events you can subscribe to:
| Event | Description |
|---|---|
show |
Emitted when a modal is completely shown |
close |
Emitted when a modal is completely closed |
<template>
<vue-accessible-modal
@show="showHandler"
@close="closeHandler"
></vue-accessible-modal>
</template>import YourAwesomeComponent from './YorAwesomeComponent.vue'
export default {
// ...
methods: {
submitHandler(e) {
console.log(e)
},
showModal() {
this.$modal.show(YourAwesomeComponent, {
props: { foo: 'bar' },
listeners: { submit: this.submitHandler },
classes: ['foo', 'bar'],
label: 'My awesome modal',
attributes: {
id: 'modal',
'data-attribute': 'foo',
},
transition: 'fade',
})
},
},
// ...
}ℹ️ Note that your modal component can contain property named
modal, which value will be applied to the modal component:
export default {
name: 'YourAwesomeComponent',
data() {
return {}
},
modal: {
classes: ['foo', { bar: true }],
label: 'foo',
attributes: {
id: 'baz',
},
},
}This gives you a convenient way of providing custom classes, label and attributes specific to modal component.
⚠️ Notice that values provided viaoptionsin object will take precedence over values provided via component'smodalproperty.
Vue.js;Typescript;Rollup(and plugins);SASS;PostCSS;Autoprefixer;