vue-a11y-dialog

Vue A11yDialog

This is a Vue.js wrapper component for a11y-dialog@7.3.0 (Demo on CodeSandbox).

• Installation
• Usage
  • Multiple dialogs
• API
• Events
• Slots
• Server-side Rendering

Installation

This library supports both Vue 3 and Vue 2. However, active maintenance is focused on Vue 3. If you still need to support Vue 2, you can stay on version 0.5.2.

Vue 3

npm install vue-a11y-dialog

Vue 2

npm install vue-a11y-dialog@0.5.2

Usage

In your main.js application file, install the component:

import { createApp } from 'vue'
import A11yDialog from 'vue-a11y-dialog'
import App from './App.vue'

createApp(App).use(A11yDialog).mount('#app')

Then use it as follows:

<template>
  <div id="app">
    <!-- ... -->
    <button type="button" @click="openDialog">
      Open dialog
    </button>

    <a11y-dialog
      id="app-dialog"
      @dialog-ref="assignDialogRef"
    >
      <template v-slot:title>
        <span>Your dialog title</span>
      </template>
      <div>
        <p>Your content</p>
      </div>
    </a11y-dialog>
  </div>
</template>

export default {
  name: 'YourComponent',

  data: () => ({
    dialog: null
  }),

  methods: {
    openDialog() {
      if (this.dialog) {
        this.dialog.show()
      }
    },

    assignDialogRef(dialog) {
      this.dialog = dialog
    }
  }
}

It's important to assign the direct reference to the dialog instance via @dialog-ref, otherwise there is no way to call its methods.

Alternatively, you can also import the component directly into your file without installing it first:

import { A11yDialog } from 'vue-a11y-dialog'
export default {
  name: 'YourComponent',

  components: {
    'a11y-dialog': A11yDialog
  },

  methods: {
    // ...
  }
}

Multiple dialogs

It's possible to use multiple dialogs in the same component, just make sure to assign the different dialog instances separately.

In your <template>:

<template>
  <div id="app">
    <!-- First dialog -->
    <a11y-dialog
      id="first-dialog"
      @dialog-ref="dialog => assignDialogRef('first', dialog)"
    >
      <template v-slot:title>
        <span>First dialog title</span>
      </template>
      <div>
        <p>Your content</p>
      </div>
    </a11y-dialog>

    <!-- Second dialog -->
    <a11y-dialog
      id="second-dialog"
      @dialog-ref="dialog => assignDialogRef('second', dialog)"
    >
      <template v-slot:title>
        <span>Second dialog title</span>
      </template>
      <div>
        <p>Your content</p>
      </div>
    </a11y-dialog>
  </div>
</template>

In your <script>:

import { A11yDialog } from 'vue-a11y-dialog';
export default {
  name: 'YourComponent',

  data: () => ({
    dialogs: {}
  }),

  methods: {
    assignDialogRef(type, dialog) {
      this.dialogs[type] = dialog
    }
  }
}

API

All a11y-dialog instance methods are available, for further documentation see here.

id

• Property: id
• Type: String
• Required: true
• Description: The unique HTML id attribute added to the dialog element, internally used by a11y-dialog to manipulate the dialog.
• Usage:

<a11y-dialog id="main-dialog">
  <!-- ... -->
</a11y-dialog>

dialog-root

• Property: dialog-root
• Type: String — CSS Selector string.
• Required: false
• Default: 'body'
• Description: The container for the dialog to be rendered into.
• Usage:

<a11y-dialog dialog-root="#dialog-root">
  <!-- ... -->
</a11y-dialog>

class-names

• Property: class-names
• Type: Object
• Required: false
• Default: {}
• Description: Object of classes for each HTML element of the dialog element. Keys are: base, overlay, document, title, closeButton. See a11y-dialog docs for reference.
• Usage:

<a11y-dialog :class-names="{ base: 'base-class', overlay: 'overlay-class' }">
  <!-- ... -->
</a11y-dialog>

title-id

• Property: title-id
• Type: String
• Required: false
• Default: Defaults to id + '-title'.
• Description: The HTML id attribute of the dialog’s title element, used by assistive technologies to provide context and meaning to the dialog window.
• Usage:

<a11y-dialog title-id="main-title">
  <!-- ... -->
</a11y-dialog>

close-button-label

• Property: close-button-label
• Type: String
• Required: false
• Default: 'Close this dialog window'
• Description: The HTML aria-label attribute of the close button, used by assistive technologies to provide extra meaning to the usual cross-mark.
• Usage:

<a11y-dialog close-button-label="Close dialog">
  <!-- ... -->
</a11y-dialog>

role

• Property: role
• Type: String
• Required: false
• Default: dialog
• Description: The role attribute of the dialog element, either dialog (default) or alertdialog to make it a modal (preventing closing on click outside of ESC key).
• Usage:

<a11y-dialog role="alertdialog">
  <!-- ... -->
</a11y-dialog>

Events

dialog-ref

• Returns: An a11y-dialog instance or undefined.
• Description: This event emits the a11y-dialog instance once the component has been initialised. When it gets destroyed, the event returns undefined. This is needed to call instance methods of the dialog, e.g. this.dialog.show().
• Usage:

<a11y-dialog @dialog-ref="assignDialogRef">
  <!-- ... -->
</a11y-dialog>

export default {
  // ...
  methods: {
    assignDialogRef(dialog) {
      this.dialog = dialog
    }
  }
}

Slots

title

• Name: title
• Description: The title of the dialog, mandatory in the document to provide context to assistive technology. Could be hidden with CSS (while remaining accessible).
• Usage:

<a11y-dialog>
  <template v-slot:title>
    <span>Your dialog title</span>
  </template>
  <!-- ... -->
</a11y-dialog>

closeButtonContent

• Name: closeButtonContent
• Default: \u00D7 (×)
• Description: The string that is the inner HTML of the close button.
• Usage:

<a11y-dialog>
  <template v-slot:closeButtonContent>
    <span>Close dialog</span>
  </template>
  <!-- ... -->
</a11y-dialog>

closeButtonPosition

• Name: closeButtonPosition
• Default: first
• Description: One of first, last, or none
• Usage:

<a11y-dialog close-button-position="last">
  <template v-slot:closeButtonContent>
    <span>Close dialog</span>
  </template>
  <!-- ... -->
</a11y-dialog>

Server-side Rendering

This is a client-only component; a11y-dialog won't render anything on the server and wait for your bundle to be executed on the client.