{"id":13635355,"url":"https://github.com/andrewvasilchuk/vue-accessible-modal","last_synced_at":"2025-03-04T23:41:29.253Z","repository":{"id":35139390,"uuid":"211041718","full_name":"andrewvasilchuk/vue-accessible-modal","owner":"andrewvasilchuk","description":"Vue.js component for accessible modals","archived":false,"fork":false,"pushed_at":"2022-12-10T04:04:51.000Z","size":405,"stargazers_count":20,"open_issues_count":14,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-21T06:19:05.362Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewvasilchuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-26T08:41:27.000Z","updated_at":"2023-09-14T01:29:09.000Z","dependencies_parsed_at":"2023-01-15T14:37:20.041Z","dependency_job_id":null,"html_url":"https://github.com/andrewvasilchuk/vue-accessible-modal","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvasilchuk%2Fvue-accessible-modal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvasilchuk%2Fvue-accessible-modal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvasilchuk%2Fvue-accessible-modal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvasilchuk%2Fvue-accessible-modal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewvasilchuk","download_url":"https://codeload.github.com/andrewvasilchuk/vue-accessible-modal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241940529,"owners_count":20045878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T00:00:44.398Z","updated_at":"2025-03-04T23:41:29.231Z","avatar_url":"https://github.com/andrewvasilchuk.png","language":"Vue","funding_links":[],"categories":["Components \u0026 Libraries","Components and plugins","UI Components [🔝](#readme)"],"sub_categories":["UI Components","Courses"],"readme":"# vue-accessible-modal\r\n\r\n\u003e Vue.js component for accessible modals.\r\n\r\n- [vue-accessible-modal](#vue-accessible-modal)\r\n  - [Features](#features)\r\n  - [Demo](#demo)\r\n  - [Installation](#installation)\r\n    - [Via NPM](#via-npm)\r\n    - [Via Yarn](#via-yarn)\r\n  - [Initialization](#initialization)\r\n    - [As a plugin](#as-a-plugin)\r\n  - [Usage](#usage)\r\n    - [Template](#template)\r\n    - [Styles](#styles)\r\n    - [API](#api)\r\n    - [Emitted events](#emitted-events)\r\n      - [Example of subscribing to events](#example-of-subscribing-to-events)\r\n    - [Example of possible usage of the library](#example-of-possible-usage-of-the-library)\r\n  - [Powered by](#powered-by)\r\n  - [License](#license)\r\n\r\n## Features\r\n\r\n- 📟 fully accessible to screen readers;\r\n- ⌨️ supports keyboard navigation;\r\n- 🎯 focus trap;\r\n- restores focus when modal is closed;\r\n- simple API.\r\n\r\n## Demo\r\n\r\n[![Edit vue-accessible-modal](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/vue-accessible-modal-9m474?fontsize=14)\r\n\r\n## Installation\r\n\r\n### Via NPM\r\n\r\n```bash\r\nnpm install vue-accessible-modal --save\r\n```\r\n\r\n### Via Yarn\r\n\r\n```bash\r\nyarn add vue-accessible-modal\r\n```\r\n\r\n## Initialization\r\n\r\n### As a plugin\r\n\r\nIt must be called before `new Vue()`.\r\n\r\n```javascript\r\nimport Vue from 'vue'\r\nimport VueAccessibleModal from 'vue-accessible-modal'\r\n\r\n// optional options\r\nconst options = {\r\n  transition: 'fade',\r\n}\r\n\r\nVue.use(VueAccessibleModal, options)\r\n```\r\n\r\n## Usage\r\n\r\n### Template\r\n\r\nFirst off you should insert the `\u003cvue-accessible-modal /\u003e` component into your `template`, this is where your modals will be rendered:\r\n\r\n```html\r\n\u003ctemplate\u003e\r\n  \u003cvue-accessible-modal /\u003e\r\n\u003c/template\u003e\r\n```\r\n\r\n### Styles\r\n\r\nThen don't forget to include core styles:\r\n\r\n`SASS`:\r\n\r\n```scss\r\n@import 'vue-accessible-modal/src/styles/core.scss';\r\n```\r\n\r\nOr already compiled `CSS`:\r\n\r\n`CSS`:\r\n\r\n```scss\r\n@import 'vue-accessible-modal/dist/index.css';\r\n```\r\n\r\n\u003e ⚠️ Note that when you import already compiled CSS you don't have ability to override `SASS` variables during build process, so it preferable to use`.scss` file. But you still have ability to override default styles and change CSS custom properties during runtime.\r\n\r\nThere are `SASS` variables you can override during build process:\r\n\r\n```scss\r\n$v-modal-holder-padding: 32px !default;\r\n$v-modal-backdrop-color: rgba(#333, 0.88) !default;\r\n$v-modal-content-background-color: #fff !default;\r\n```\r\n\r\nAnd [`CSS` custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) you can override during runtime:\r\n\r\n```scss\r\n:root {\r\n  --v-modal-holder-padding: #{$v-modal-holder-padding};\r\n  --v-modal-backdrop-color: #{$v-modal-backdrop-color};\r\n  --v-modal-content-background-color: #{$v-modal-content-background-color};\r\n}\r\n```\r\n\r\n### API\r\n\r\n\u003e 🌈 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.\r\n\r\nWhen 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.\r\n\r\n\u003e ⚠️ 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 `\u003cbutton @click=\"$modal.close()\"\u003eClose dialog\u003c/button\u003e`.\r\n\r\n`$modal.show(component: VueComponent, options?: object)` method accepts two arguments:\r\n\r\n1. `component`: Vue.js component you want to display in the modal.\r\n2. `options`: object through which you can customize the behaviour of the modal.\r\n\r\n`options` object can contain the following properties:\r\n\r\n| Property     | Description                                                                                       |\r\n| ------------ | ------------------------------------------------------------------------------------------------- |\r\n| `props`      | `props` that will be passed to provided component via `v-bind=\"props\"`                            |\r\n| `listeners`  | an object with listeners to listen to events emitted from passed component via `v-on=\"listeners\"` |\r\n| `classes`    | custom classes that will be applied to the modal                                                  |\r\n| `label`      | value of `aria-label` attribute                                                                   |\r\n| `attributes` | any attribute you want to bind to the modal                                                       |\r\n| `transition` | `name` of the transition that will be passed to `transition` component                            |\r\n\r\n\u003e ℹ️ Note that through `options.attributes` you can bind any HTML attribute to a modal.\r\n\u003e For example if you want to bind `aria-labelledby` or `aria-describedby`, you can do the following:\r\n\r\n```js\r\n{\r\n  props: { },\r\n  listeners: { },\r\n  attributes: {\r\n    id: 'foo',\r\n    'aria-labelledby': 'foo',\r\n    'aria-describedby': 'bar',\r\n  },\r\n}\r\n```\r\n\r\nTo close modal from anywhere in your app you should call `this.$modal.close()` method.\r\n\r\n\u003e 🆕 Support version 0.4.0\r\n\r\nSince version `0.4.0` you can use `vue-accessible-modal` to confirm user actions.\r\n`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).\r\n\r\nYour confirm component should accept three props: `message` , `resolve` and `reject` (since `$modal.confirm` leverages `Promise`).\r\n\r\nBellow is the example of usage of `$modal.confirm`:\r\n\r\n`ConfirmComponent.vue`:\r\n\r\n```html\r\n\u003ctemplate\u003e\r\n  \u003csection\u003e\r\n    \u003ch1\u003e{{ message }}\u003c/h1\u003e\r\n    \u003cbutton type=\"button\" @click=\"resolveHandler\"\u003eResolve\u003c/button\u003e\r\n    \u003cbutton type=\"button\" @click=\"rejectHandler\"\u003eReject\u003c/button\u003e\r\n  \u003c/section\u003e\r\n\u003c/template\u003e\r\n```\r\n\r\n```ts\r\nimport Vue from 'vue'\r\n\r\nexport default Vue.extend({\r\n  name: 'ConfirmComponent',\r\n  // required props\r\n  props: {\r\n    message: {\r\n      type: String,\r\n      required: true,\r\n    },\r\n    resolve: {\r\n      type: Function,\r\n      required: true,\r\n    },\r\n    reject: {\r\n      type: Function,\r\n      required: true,\r\n    },\r\n  },\r\n  methods: {\r\n    resolveHandler() {\r\n      // this value will be passed to `then`\r\n      this.resolve('foo')\r\n    },\r\n    rejectHandler() {\r\n      // this value will be passed to `catch`\r\n      this.reject('bar')\r\n    },\r\n  },\r\n})\r\n```\r\n\r\n```ts\r\nimport ConfirmComponent from 'path/to/confirm/component'\r\n\r\nexport default {\r\n  // ...\r\n  methods: {\r\n    confirm() {\r\n      this.$modal\r\n        .confirm(ConfirmComponent, 'Do you like JavaScript?')\r\n        .then(val =\u003e {\r\n          console.log(val)\r\n        })\r\n        .catch(val =\u003e {\r\n          console.log(val)\r\n        })\r\n        .finally(() =\u003e {\r\n          this.$modal.close()\r\n        })\r\n    },\r\n  },\r\n  // ...\r\n}\r\n```\r\n\r\n### Emitted events\r\n\r\n`\u003cvue-accessible-modal\u003e` component emits some events you can subscribe to:\r\n\r\n| Event   | Description                               |\r\n| ------- | ----------------------------------------- |\r\n| `show`  | Emitted when a modal is completely shown  |\r\n| `close` | Emitted when a modal is completely closed |\r\n\r\n#### Example of subscribing to events\r\n\r\n```html\r\n\u003ctemplate\u003e\r\n  \u003cvue-accessible-modal\r\n    @show=\"showHandler\"\r\n    @close=\"closeHandler\"\r\n  \u003e\u003c/vue-accessible-modal\u003e\r\n\u003c/template\u003e\r\n```\r\n\r\n### Example of possible usage of the library\r\n\r\n```js\r\nimport YourAwesomeComponent from './YorAwesomeComponent.vue'\r\n\r\nexport default {\r\n  // ...\r\n  methods: {\r\n    submitHandler(e) {\r\n      console.log(e)\r\n    },\r\n    showModal() {\r\n      this.$modal.show(YourAwesomeComponent, {\r\n        props: { foo: 'bar' },\r\n        listeners: { submit: this.submitHandler },\r\n        classes: ['foo', 'bar'],\r\n        label: 'My awesome modal',\r\n        attributes: {\r\n          id: 'modal',\r\n          'data-attribute': 'foo',\r\n        },\r\n        transition: 'fade',\r\n      })\r\n    },\r\n  },\r\n  // ...\r\n}\r\n```\r\n\r\n\u003e ℹ️ Note that your modal component can contain property named `modal`, which value will be applied to the modal component:\r\n\r\n```js\r\nexport default {\r\n  name: 'YourAwesomeComponent',\r\n  data() {\r\n    return {}\r\n  },\r\n  modal: {\r\n    classes: ['foo', { bar: true }],\r\n    label: 'foo',\r\n    attributes: {\r\n      id: 'baz',\r\n    },\r\n  },\r\n}\r\n```\r\n\r\nThis gives you a convenient way of providing custom `classes`, `label` and `attributes` specific to modal component.\r\n\r\n\u003e ⚠️ Notice that values provided via `options` in object will take precedence over values provided via component's `modal` property.\r\n\r\n## Powered by\r\n\r\n- `Vue.js`;\r\n- `Typescript`;\r\n- `Rollup` (and plugins);\r\n- `SASS`;\r\n- `PostCSS`;\r\n- `Autoprefixer`;\r\n\r\n## License\r\n\r\n[MIT](http://opensource.org/licenses/MIT)\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewvasilchuk%2Fvue-accessible-modal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewvasilchuk%2Fvue-accessible-modal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewvasilchuk%2Fvue-accessible-modal/lists"}