@ithaka/bonsai/documentation/pages/components/modal.md

ITHAKA core styling

---
title: Modal
description: Modals open in a secondary window atop of the page being viewed. They are used for a variety of reasons, including displaying information and allowing for user input. Use judiciously as they obstruct the user workflow.
sass: ./scss/_modals.scss
js: ./js/bonsai.modal.js
foundation: http://foundation.zurb.com/sites/docs/reveal.html
---

## How to Use

### Basics

```html_example
<button type="button" class="button" data-open="default-modal">Click me for a modal!</button>
<div class="reveal" id="default-modal" data-reveal data-icon="shopping-cart" data-circle-color="alert">
    <h1>I am modal</h1>
    <p>I am a paragraph inside a modal!</p>
    <button class="close-button" data-close aria-label="Close modal" type="button">
        <span aria-hidden="true">&times;</span>
    </button>
</div>
```

### Size of modal

The default size of a modal is 600px, but adding a class of `small` makes it 25% smaller and adding
a class of `large` makes it 25% larger.
```html_example
<button type="button" class="button" data-open="small-modal">Click me for small modal!</button>
<div class="reveal small" id="small-modal" data-reveal data-icon="shopping-cart" data-circle-color="alert">
    <h1>I am a small modal</h1>
    <p>I am a paragraph inside a small modal!</p>
    <button class="close-button" data-close aria-label="Close modal" type="button">
        <span aria-hidden="true">&times;</span>
    </button>
</div>
<button type="button" class="button" data-open="large-modal">Click me for large modal!</button>
<div class="reveal large" id="large-modal" data-reveal data-icon="shopping-cart" data-circle-color="alert">
    <h1>I am a large modal</h1>
    <p>I am a paragraph inside a large modal!</p>
    <button class="close-button" data-close aria-label="Close modal" type="button">
        <span aria-hidden="true">&times;</span>
    </button>
</div>
```

## Accessibility

1. When a modal opens, move focus to that modal.
1. Ensure modal content is accessible to keyboard users by allowing the *Escape* key to close the modal, and by providing keyboard access to content and fields within the modal.
1. Clearly indicate to a user that they are in a modal (role = "dialog").


## Guidelines
1. Blur or darken the main window.
1. Leave space around the modal so the contents of the main document are not totally obscured.
1. Make sure there is a clear way for a user to leave the modal, such as a close button in the upper right hand corner.
1. Placing the modal closer to the top of the page rather than in the exact center. Doing this minimizes the risk of having the modal cut off at the bottom, and users are still be able to scroll down to view the entire modal.  Moreover, the browser scrollbar is available in small browser windows.


## Avoid
1. Multiple navigation mechanisms within a modal. Typically, modals consists of a main call to action and an escape or closing call to action.
1. Modals that are not user initiated. Modals obscure the page someone is viewing creating distraction and frustration.