Skip to content
A simple modal for accessible Ember applications.
Branch: master
Clone or download
Latest commit fa53a8d May 6, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
addon tidied up Apr 23, 2019
app removing extra components Apr 18, 2019
config inital commit Apr 18, 2019
tests updated so modal renders correctly Apr 23, 2019
vendor inital commit Apr 18, 2019
.editorconfig inital commit Apr 18, 2019
.ember-cli adding inert Apr 21, 2019
.eslintignore inital commit Apr 18, 2019
.eslintrc.js inital commit Apr 18, 2019
.gitignore inital commit Apr 18, 2019
.npmignore inital commit Apr 18, 2019
.template-lintrc.js inital commit Apr 18, 2019
.travis.yml inital commit Apr 18, 2019
.watchmanconfig inital commit Apr 18, 2019
CONTRIBUTING.md inital commit Apr 18, 2019
LICENSE.md inital commit Apr 18, 2019
README.md Update README.md May 6, 2019
ember-cli-build.js inital commit Apr 18, 2019
index.js adding inert Apr 21, 2019
jsconfig.json adding inert Apr 21, 2019
package-lock.json updated so modal renders correctly Apr 23, 2019
package.json updated so modal renders correctly Apr 23, 2019
testem.js inital commit Apr 18, 2019

README.md

Ember A11y Modal

This addon is intended to provide a simple, accessible, button-triggered modal. For the user with a screen reader, either the modal will exist, or the rest of the page will exist, but never both at the same time.

Please read all of the design details before considering this modal for your application.

Compatibility

  • Ember.js v3.8.0 or above
  • Ember CLI v3.8.0 or above

Installation

Once this addon is published:

ember install e-a11y-modal

Design

This modal was intentionally designed, and as a result may not fit into an existing application, if it has not previously considered accessibility and other best practices for front-end web design and development. It is intended to be used with application development that follows the best practices of web design and development, and considers accessibility and the user experience from a practical perspective.

The following should be kept in mind when considering use of this addon:

  • this addon uses the inert browser polyfill (see https://github.com/WICG/inert).
  • the modal has a z-index of 10.
  • when triggered, the initial focus placement is on the outside of the modal so the entire content can be read out. While this is a departure from current WCAG advice, many accessibility experts agree that this is better for user experience.
  • the modal has a close button on the top right of the modal, but can also be closed by pressing the ESC key.
  • when the modal is open, scrolling of content underneath the modal is prevented.
  • when the modal is open, focus (either by TAB key or virtual cursor) will not reach the window underneath, but users will still be able to reach the URL bar (users can typically do this anyway by pressing the F6 key)

Addons & libraries used in making this addon:

  • @ember/optional-features (to turn off the wrapping div in an Ember App)
  • wicg-inert to add the inert functionality
  • ember-wormhole (this will be used until Ember provides this functionality in a native way)

Usage

  • authors must only use one modal per page.
  • authors must put all application content inside a landmark element (see https://www.w3.org/WAI/PF/aria/roles#landmark_roles).
  • authors must provide a value for buttonText.
  • authors must provide a value for modalHeadingText.

Example: standard usage

<ModalWindow
  @modalHeadingText="Modal Title"
  @buttonText="I am the modal trigger button">
  {{!-- Any modal content can go in this block --}}
</ModalWindow>

Example: page layout

When the modal is triggered, the landmarks will be marked with inert and aria-hidden="true" will be applied, which will effectively trap the focus inside of the modal while it is open. For the user with a screen reader, either the modal will exist, or the rest of the page will exist, but never both at the same time.

<body>
  
  <header>
    {{!-- header block content here --}}
      <ModalWindow
        @modalHeadingText="Modal Title"
        @buttonText="Login">
          {{!-- Any modal content can go in this block --}}
      </ModalWindow>
  </header>
  
  <main>
    {{!-- main block content here --}}
  </main>

  <footer>
    {{!-- footer block content here --}}
  </footer>

</body>

Contributing

Contributions to this addon are welcome. Contributors should consider the design constraints (listed above in "Design" and "Usage") when submitting a PR for consideration. Please ensure that any PR includes what is being done, tests, and any screenshots that may aid in consideration for inclusion in this addon.

License

This project is licensed under the MIT License.

You can’t perform that action at this time.