Modals - Joystick Design System

Display content in a layer above the app.

Modals are most commonly used to interrupt a user's flow to show or capture important information.

The Joystick modal component is primarily comprised of two parts: the dialogue - .joy-modal__dialogue and the overlay - .joy-modal__overlay, both of which are wrapped in a .joy-modal container.

Since modals are most commonly injected into a page, the best practice is to inject the modal at the very end of the <body> element. Modals rely heavily on fixed positioning and specific high-value z-indexes which can break a page layout if they are nested any deeper in the markup.

After you inject the modal, you will need to add the class .joy-modal-open to the <body> element and .joy-modal-show to the .joy-modal element. This will make the modal visible and apply transitions when applicable.

The .joy-modal-show class is needed to specify which modal you would like to display, should you have multiple modal elements on a single page.

Base

The default modal is used in the majority of use cases. Modals have a default width of 80% of the viewport width on smaller screens, and 50% of the viewport width on larger ones. They also have max- and min-widths set as well to keep them from getting too wide or too narrow.

Modals will grow vertically to accomodate their content, but once they near the height of the viewport, the .joy-modal__content container will begin to scroll. However, .joy-modal__header and .joy-modal__footer will always be visible to the user when they are being used.

<div class="joy-modal joy-modal-show">
  <div class="joy-modal__dialogue">
    <div class="joy-modal__content">
      <p>Hello. I'm a simple modal.</p>
      <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et ad alias optio fugiat dolores? Corporis quibusdam eligendi qui ad unde quod debitis ratione laudantium molestiae nulla reiciendis, nesciunt mollitia hic.</p>
    </div>
  </div>
  <div class="joy-modal__overlay"></div>
</div>

Header & Footer

Add an optional header or footer to any modal. .joy-modal__header and .joy-modal__footer elements should be placed directly before and after the .joy-modal__content element respectively.

<div class="joy-modal joy-modal-show">
  <div class="joy-modal__dialogue joy-modal__dialogue--scale">
    <div class="joy-modal__header">
      <h2 class="joy-text-heading--small">Modal Header</h2>
    </div>
    <div class="joy-modal__content">
      <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et ad alias optio fugiat dolores? Corporis quibusdam eligendi qui ad unde quod debitis ratione laudantium molestiae nulla reiciendis, nesciunt mollitia hic.</p>
    </div>
    <div class="joy-modal__footer">
      <button class="joy-button joy-button--link joy-button--small joy-m-right--medium">Cancel</button>
      <button class="joy-button joy-button--small">Save</button>
    </div>
  </div>
  <div class="joy-modal__overlay joy-modal__overlay--fade"></div>
</div>

Transitions

Modals do not have any transitions built in by default. Add these classes transtion classes to the dialogue and overlay elements in order to apply transitions when they are shown/hidden.

<div class="joy-modal joy-modal-show joy-modal--fade">
  <div class="joy-modal__dialogue joy-modal__dialogue--scale">
    <div class="joy-modal__content">
      <p>This is the modal. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Et ad alias optio fugiat dolores? Corporis quibusdam eligendi qui ad unde quod debitis ratione laudantium molestiae nulla reiciendis, nesciunt mollitia hic.</p>
    </div>
  </div>
  <div class="joy-modal__overlay joy-modal__overlay--fade"></div>
</div>

View Demo with Transitions

Classes Overview

Class	Applied to	Usage	Comments
`.joy-modal-open`	`<body>`	Required	This is class needs to be toggled when showing/hiding modals
`.joy-modal`	`<div>`	Required	Fixed position wrapper for modal elements. Should be inserted as a direct descendant of `<body>`
`.joy-modal-show`	`.joy-modal`	Required	Apply to the specific `.joy-modal` you want to appear
`.joy-modal__dialouge`	`<div>`	Required	Container for modal content, direct descendant of `.joy-modal`
`.joy-modal__overlay`	`<div>`	Required	Opaque overlay, direct descendant of `.joy-modal`
`.joy-modal__header`	`<div>`	Optional	Applies a header to modal dialogue, direct descendant of `.joy-modal__dialogue`
`.joy-modal__content`	`<div>`	Required	Main content of modal dialogue, direct descendant of `.joy-modal__dialogue`
`.joy-modal__footer`	`<div>`	Optional	Applies a footer to modal dialogue, direct descendant of `.joy-modal__dialogue`
`.joy-modal__dialogue--scale`	`.joy-modal__dialogue`	Optional	Applies a scale transition effect to the dialogue when showing/hiding modals.
`.joy-modal__overlay--fade`	`.joy-modal__overlay`	Optional	Applies a fade transition effect to the overlay when showing/hiding modals.
`.joy-modal--no-transition`	`.joy-modal`	Optional	Removes modal transition, making modals appear/disappear instantly

Joystick jQuery Plugin

The following documentation requires the Joystick jQuery plugin. Check out the repo for install instructions.

Usage

The modal plugin toggles your hidden modal on demand, via data attributes or JavaScript.

It also adds .joy-modal-open to the <body> to override default scrolling behavior, applies .joy-modal-open to the specified modal element, and generates the .joy-modal__overlay to provide a click area for dismissing shown modals when clicking outside the modal.

Via data attributes

Activate a modal without writing JavaScript. Set data-toggle="modal" on a controller element, like a button, along with a data-target="#foo" or href="#foo" to target a specific modal to toggle.

<button type="joy-button" data-toggle="modal" data-target="#myModal">Launch modal</button>

Attribute	Value	Optional	Description
`data-toggle`	`modal`	Required	Apply to a trigger element such as a `<button>` or `<a>` to initialize a modal toggle interaction
`data-target`	`id` of a modal element	Required	Used with `data-toggle` to specify which modal to show
`data-overlay`	`static`	Optional	Also applied to the trigger element, this will disable closing the modal when the overlay is clicked
`data-dismiss`	`modal`	Optional	Apply to any trigger element within a `.joy-modal` to close the containing modal when open

Via JavaScript

Call a modal with id myModal with a single line of JavaScript:

$('#myModal').modal(options);

Options

Options can be passed via data attributes or JavaScript. For data attributes, append the option name to data-, as in data-overlay="".

Name	Type	Default	Description
overlay	bool or the string `'static'`	true	True to close the modal on click or 'static' to prevent the modal from being closed when clicking the overlay.
keyboard	bool	true	If true the modal will close when pressing Esc key, otherwise false.
show	bool	true	Shows the modal when initialized.

Methods

Activates your content as a modal. Accepts an optional options object.

$('#myModal').modal({
  overlay: 'static'
});

Manually toggles a modal. Returns to the caller before the modal has actually been shown or hidden (i.e. before the shown.joy.modal or hidden.joy.modal event occurs).

$('#myModal').modal('toggle');

Manually opens a modal. Returns to the caller before the modal has actually been shown (i.e. before the shown.joy.modal event occurs).

$('#myModal').modal('show');

Manually hides a modal. Returns to the caller before the modal has actually been hidden (i.e. before the hidden.joy.modal event occurs).

$('#myModal').modal('hide');

Events

Joystick’s modal class exposes a few events for hooking into modal functionality. All modal events are fired at the modal itself (i.e. at the <div class="modal">).

Event Type	Description
show.joy.modal	This event fires immediately when the show instance method is called. If caused by a click, the clicked element is available as the `relatedTarget` property of the event.
shown.joy.modal	his event is fired when the modal has been made visible to the user (will wait for CSS transitions to complete). If caused by a click, the clicked element is available as the `relatedTarget` property of the event.
hide.joy.modal	This event is fired immediately when the `hide` instance method has been called.
hidden.joy.modal	This event is fired when the modal has finished being hidden from the user (will wait for CSS transitions to complete).

$('#myModal').on('show.joy.modal', function (e) {
  // do something...
});
$('#myModal').on('hidden.joy.modal', function (e) {
  // do something...
});