108 | Introduction 109 |
110 | 111 |112 | Micromodal.js is a lightweight, configurable and a11y-enabled modal library written in pure 113 | JavaScript 114 |
115 | 116 |117 | It enables you to create WAI-ARIA guidelines compliant modal dialogs, 119 | with confidence and with minimal configuration. At just 1.9kb minified and gzipped, its a tiny library for big 120 | change. 121 |
122 | 123 | 124 |136 | Following are some of the interactions handled by the library:- 137 |
138 | 139 |-
140 |
- Closing modal on overlay click 141 |
- Closing modal on
esc
button press
142 | - Toggling
aria-hidden
attribute on modal
143 | - Trapping tab focus within the modal 144 |
- Maintaining focus position before and after toggling modal 145 |
- Focusing on the first focusable element within the modal 146 |
151 | Installation 152 |
153 | 154 |
155 | Micromodal is available on npm
and can be installed from the command line via npm or yarn
156 |
159 | npm install micromodal --save // via npm
160 | yarn add micromodal --save // via yarn
161 |
162 |
163 | 164 | You can also download or link to the latest compiled version using the CDN. 165 |
166 | 167 |
168 | https://unpkg.com/micromodal/dist/micromodal.min.js
169 |
170 |
171 |
172 |
173 | 174 | Usage 175 |
176 | 177 |178 | Designed to be easy to use, it does most of the heavy lifting behind the scenes and exposes a simple api to 179 | interact with the dom. 180 |
181 | 182 |
183 | Typically modals have an overlay which cover the rest of the content. To achieve this, it is normal to put the
184 | modal code just before the closing body
tag, so that the modal overlay is relative to the body
185 | and covers the whole screen.
186 |
189 | 1. Add the modal markup 190 |
191 | 192 |193 | The following html structure is expected for the modal to work. It can of course be extended to suit your 194 | needs. As an example of the customization, see the source code of the demo modal here. 197 |
198 | 199 |
200 | <!-- [1] -->
201 | <div id="modal-1" aria-hidden="true">
202 |
203 | <!-- [2] -->
204 | <div tabindex="-1" data-micromodal-close>
205 |
206 | <!-- [3] -->
207 | <div role="dialog" aria-modal="true" aria-labelledby="modal-1-title" >
208 |
209 |
210 | <header>
211 | <h2 id="modal-1-title">
212 | Modal Title
213 | </h2>
214 |
215 | <!-- [4] -->
216 | <button aria-label="Close modal" data-micromodal-close></button>
217 | </header>
218 |
219 | <div id="modal-1-content">
220 | Modal Content
221 | </div>
222 |
223 | </div>
224 | </div>
225 | </div>
226 |
227 |
228 | -
229 |
-
230 | This is the outermost container of the modal. Its job is to toggle the display of the modal. It is
231 | important that every modal have a unique
id
. By default thearia-hidden
will be 232 |true
. Micromodal takes care of toggling the value when required. 233 |
234 | -
235 | This is the
div
which acts as the overlay for the modal. Notice the 236 |data-micromodal-close
on it. This is a special attribute which indicates that the element that 237 | it is on should trigger the close of the modal on click. If we remove that attribute, clicking on the 238 | overlay will not close the modal anymore. 239 |
240 | -
241 | The
role="dialog"
attribute is used to inform assistive technologies that content within is 242 | separate from the rest of the page. Additionally, thearia-labelledby="modal-1-title"
attribute 243 | points to theid
of the modal title. This is to help identify the purpose of the modal. 244 |
245 | -
246 | Ensuring that all buttons have a
aria-label
attribute which defines the action of the button. 247 | Notice thedata-micromodal-close
attribute is used on the button since we want to close the 248 | modal on press. 249 |
250 |
255 | 2. Add micromodal.js 256 |
257 | 258 |
259 | If you included the compiled file from the CDN into your project, you will have access to a
260 | MicroModal
global variable, which you can use to instantiate the module.
261 |
264 | In cases with a modular workflow, you can directly import the module into your project. 265 |
266 | 267 |
268 | import MicroModal from 'micromodal'; // es6 module
269 | var MicroModal = require('micromodal'); // commonjs module
270 |
271 |
272 | 273 | 3. Use with data attributes 274 |
275 | 276 |
277 | Set data-micromodal-trigger="modal-1"
on an element, like a button or link, on whose click you
278 | want to show the modal. The value of the attribute, in this case modal-1
should correspond to the
279 | id
of the modal you want to toggle.
280 |
283 | Then instantiate the MicroModal
module, so that it takes care of all the bindings for you.
284 |
287 | MicroModal.init();
288 |
289 |
290 |
291 | 292 | Example:- 293 |
294 | 295 |306 | 3.1. Custom data attributes 307 |
308 | 309 |
310 | You can also specify custom attributes to open and close modals. Set data-custom-open="modal-1"
311 | to any element on the page and pass it in init
method as parameter of openTrigger
.
312 |
315 | The working and usage is same as data-micromodal-trigger
, but with your own defined data
316 | attribute, in this case it's data-custom-open
317 |
320 | Similarly, you can also define custom close attribute. Example:- 321 |
322 | 323 |
324 | <button data-custom-close="modal-1">close</button>
325 |
326 |
327 | 328 | 4. Use with javascript 329 |
330 | 331 |
332 | You can also trigger and close modals programmatically using the show
and close
333 | methods on the MicroModal
object. Example:
334 |
337 |
338 | MicroModal.show('modal-id'); // [1]
339 | MicroModal.close('modal-id'); // [2]
340 |
341 | MicroModal.show(modalElement); // [3]
342 | MicroModal.close(modalElement); // [4]
343 |
344 | // [5]
345 | MicroModal.show(modalElement, {
346 | onShow: modal => console.info(`${modal.id} is shown`),
347 | onClose: modal => console.info(`${modal.id} is hidden`),
348 | });
349 |
350 |
351 |
352 | -
353 |
-
354 | If the argument passed to the
show
method is a string, it corresponds to theid
of the modal to be open. 355 |
356 | -
357 | If the argument passed to the
close
method is a string, it corresponds to theid
of the modal to be closed. 358 |
359 | -
360 | If you pass in an element to the
show
method, it will be used as the modal to be open. 361 |
362 | -
363 | If you pass in an element to the
close
method, it will be used as the modal to be closed. 364 |
365 | -
366 | If you pass in a config object to the
show
orclose
methods, it will apply only to this 367 | modal. 368 |
369 |
372 | Configuration 373 |
374 |
375 | The init
and show
methods accept an optional configuration object. This allows you
376 | to set custom callbacks and control behaviour of the modal. Example:-
377 |
380 | MicroModal.init({
381 | onShow: modal => console.info(`${modal.id} is shown`), // [1]
382 | onClose: modal => console.info(`${modal.id} is hidden`), // [2]
383 | openTrigger: 'data-custom-open', // [3]
384 | closeTrigger: 'data-custom-close', // [4]
385 | openClass: 'is-open', // [5]
386 | disableScroll: true, // [6]
387 | disableFocus: false, // [7]
388 | awaitOpenAnimation: false, // [8]
389 | awaitCloseAnimation: false, // [9]
390 | debugMode: true // [10]
391 | });
392 |
393 |
394 | -
395 |
-
396 | onShow
function
397 |398 | This is fired when the modal is opening. The function receives the modal object as the first parameter and 399 | the trigger element as second parameter 400 |
401 |
402 | -
403 | onClose
function
404 |405 | This is fired when the modal is closing. The function receives the modal object as the first parameter and 406 | the trigger element as second parameter 407 |
408 |
409 | -
410 | openTrigger
string
411 |412 | Custom data attribute to open modal. Default is
414 |data-micromodal-trigger
413 |
415 | -
416 | closeTrigger
string
417 |418 | Custom data attribute to close modal. Default is
420 |data-micromodal-close
419 |
421 | -
422 | openClass
string
423 |424 | Custom class to be applied when modal is open. Default class is
426 |is-open
425 |
427 | -
428 | disableScroll
boolean
429 |430 | This disables scrolling on the page while the modal is open. The default value is
432 |false
431 |
433 | -
434 | disableFocus
boolean
435 |436 | Disable auto focus on first focusable element. Default is
438 |false
437 |
439 | -
440 | awaitOpenAnimation
boolean
441 |442 | Set this to
445 |true
if using css animations to open the modal. This allows it to wait for the 443 | animation to finish before focusing on an element inside the modal. Default isfalse
444 |
446 | -
447 | awaitCloseAnimation
boolean
448 |449 | Set this to
453 |true
if using css animations to hide the modal. This allows it to wait for the 450 | animation to finish before 451 | removing it from the DOM. Default isfalse
452 |
454 | -
455 | debugMode
boolean
456 |457 | This option suppresses the console warnings if passed as
460 |true
. The default value is 458 |false
459 |
461 |
464 | Styling 465 |
466 | 467 |468 | Micromodal does not make any stylistic choices about your modal and hence comes with no styling at all. It 469 | does not even toggle the visibility of the modal. You are free to style the modal in anyway you wish. 470 |
471 | 472 |
473 | At the very least, we recommend the following bit of css
to toggle the modal.
474 |
477 | .modal {
478 | display: none;
479 | }
480 |
481 | .modal.is-open {
482 | display: block;
483 | }
484 |
485 |
486 | 487 | In case you do want some default styles to get started quickly, you can refer to the styles and the 488 | corresponding markup of the demo modal here:- 489 |
490 | 491 |492 | Demo markup and styles. 494 |
495 |