Component

Modal dialogue (experimental)

Shows only one section, with no other navigation options, until the user finishes the immediate task

Use where the application has gotten into a state from which it shouldn’t or can’t proceed without input from the user or the state of the current page needs to be preserved.

Modal instances are automatically initialised and their state can be changed programmatically using bounded functions (e.g. $modalDialogue.open() and $modalDialogue.close()).

When the component is not limited to presenting information (e.g. an alert dialog or an informative dialog) and it contains interactive elements (e.g. form elements) you should use the aria_label attribute. This will provide context around what the modal dialogue is about and will prevent it from being too verbose for screen reader users (if aria_label is not specified the whole modal content will be read out).

Modal components must be a direct descendant of the <body> element; we recommend placing it toward the end of the document for performance considerations.

This component is currently experimental. If you are using it, please feed back any research findings to the Content Publisher team.

Search for usage of this component on GitHub.

How it looks (preview) (preview all)

How to call this component

<%= render "govuk_publishing_components/components/button", {
  text: "Open modal",
  data_attributes: {
    toggle: "modal",
    target: "modal-default"
  }
} %>
<%= render "govuk_publishing_components/components/modal_dialogue", {
  id: "modal-default"
} do %>
  <h1 class="govuk-heading-l">Modal title</h1>
<p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed imperdiet fringilla dictum. Morbi at vehicula augue. Pellentesque varius orci et augue pellentesque, sed elementum massa posuere. Curabitur egestas consectetur arcu, in porta lorem sagittis eu. Nulla facilisi. Sed scelerisque ligula lectus. Nulla et ligula a eros laoreet lacinia nec et ipsum. Ut sagittis sapien est, ut blandit risus laoreet at. Vestibulum vitae erat sed dolor ultricies efficitur.</p>
<% end %>

Accessibility acceptance criteria

The modal dialogue box must:

  • receive focus on open
  • inform the user that it is a dialogue
  • provide a heading that says what the dialogue is about
  • prevent mouse clicks outside the dialogue while open
  • prevent scrolling the page while the dialogue is open
  • prevent tabbing to outside the dialogue while open
  • can be operable with a keyboard (allows the ESC key to close the dialogue)
  • return focus to last focused element on close

Other examples

Standard options

This component uses the component wrapper helper. It accepts the following options and applies them to the parent element of the component. See the component wrapper helper documentation for more detail.

  • id - accepts a string for the element ID attribute
  • data_attributes - accepts a hash of data attributes
  • aria - accepts a hash of aria attributes
  • classes - accepts a space separated string of classes, these should not be used for styling and must be prefixed with js-
  • margin_bottom - accepts a number from 0 to 9 (0px to 60px) using the GOV.UK Frontend spacing scale (defaults to no margin)
  • role - accepts a space separated string of roles
  • lang - accepts a language attribute value
  • open - accepts an open attribute value (true or false)
  • hidden - accepts an empty string, ‘hidden’, or ‘until-found’
  • tabindex - accepts an integer. The integer can also be passed as a string
  • dir - accepts ‘rtl’, ‘ltr’, or ‘auto’
  • type - accepts any valid type attribute e.g. ‘button’, ‘submit’, ‘text’
  • rel - accepts any valid rel attribute e.g. ‘nofollow’
  • target - accepts a valid target attribute e.g. ‘_blank’
  • title - accepts any string
  • draggable - accepts a draggable attribute value (“true” or “false”)

Wide (preview)

A wide version of the modal dialogue will provide the same width with the main container

<%= render "govuk_publishing_components/components/button", {
  text: "Open wide modal",
  data_attributes: {
    toggle: "modal",
    target: "modal-wide"
  }
} %>
<%= render "govuk_publishing_components/components/modal_dialogue", {
  id: "modal-wide",
  wide: true
} do %>
  <h1 class="govuk-heading-l">Modal title</h1>
  <p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed imperdiet fringilla dictum. Morbi at vehicula augue. Pellentesque varius orci et augue pellentesque, sed elementum massa posuere. Curabitur egestas consectetur arcu, in porta lorem sagittis eu. Nulla facilisi. Sed scelerisque ligula lectus. Nulla et ligula a eros laoreet lacinia nec et ipsum. Ut sagittis sapien est, ut blandit risus laoreet at. Vestibulum vitae erat sed dolor ultricies efficitur.</p>
<% end %>

With form (preview)

Modal dialogue with form elements inside to show how it prevents tabbing to outside the dialogue when open while preserving the tabindex on focusable elements

<%= render "govuk_publishing_components/components/button", {
  text: "Open modal with form",
  data_attributes: {
    toggle: "modal",
    target: "modal-with-form"
  }
} %>
<%= render "govuk_publishing_components/components/modal_dialogue", {
  id: "modal-with-form",
  aria_label: "Search contacts"
} do %>
  <h1 class="govuk-heading-l">Search contacts</h1>
  <label class="govuk-label govuk-visually-hidden" for="contacts">Search contacts</label>
  <div class="govuk-form-group"><input class="govuk-input" id="contacts"></div>
  <button class="govuk-button">Insert contact</button>
<% end %>

With large content (preview)

Modal dialogue with a large block content to show how the modal scrolls withing the page and how it prevents scrolling the page while the dialogue is open

<%= render "govuk_publishing_components/components/button", {
  text: "Open modal with large content",
  data_attributes: {
    toggle: "modal",
    target: "modal-with-large-content"
    }
  } %>
<%= render "govuk_publishing_components/components/modal_dialogue", {
  id: "modal-with-large-content"
} do %>
  <h1 class="govuk-heading-l">Modal title</h1>
  <p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed imperdiet fringilla dictum. Morbi at vehicula augue. Pellentesque varius orci et augue pellentesque, sed elementum massa posuere. Curabitur egestas consectetur arcu, in porta lorem sagittis eu. Nulla facilisi. Sed scelerisque ligula lectus. Nulla et ligula a eros laoreet lacinia nec et ipsum. Ut sagittis sapien est, ut blandit risus laoreet at. Vestibulum vitae erat sed dolor ultricies efficitur.</p>
  <p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed imperdiet fringilla dictum. Morbi at vehicula augue. Pellentesque varius orci et augue pellentesque, sed elementum massa posuere. Curabitur egestas consectetur arcu, in porta lorem sagittis eu. Nulla facilisi. Sed scelerisque ligula lectus. Nulla et ligula a eros laoreet lacinia nec et ipsum. Ut sagittis sapien est, ut blandit risus laoreet at. Vestibulum vitae erat sed dolor ultricies efficitur.</p>
  <p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed imperdiet fringilla dictum. Morbi at vehicula augue. Pellentesque varius orci et augue pellentesque, sed elementum massa posuere. Curabitur egestas consectetur arcu, in porta lorem sagittis eu. Nulla facilisi. Sed scelerisque ligula lectus. Nulla et ligula a eros laoreet lacinia nec et ipsum. Ut sagittis sapien est, ut blandit risus laoreet at. Vestibulum vitae erat sed dolor ultricies efficitur.</p>
  <p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed imperdiet fringilla dictum. Morbi at vehicula augue. Pellentesque varius orci et augue pellentesque, sed elementum massa posuere. Curabitur egestas consectetur arcu, in porta lorem sagittis eu. Nulla facilisi. Sed scelerisque ligula lectus. Nulla et ligula a eros laoreet lacinia nec et ipsum. Ut sagittis sapien est, ut blandit risus laoreet at. Vestibulum vitae erat sed dolor ultricies efficitur.</p>
  <p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed imperdiet fringilla dictum. Morbi at vehicula augue. Pellentesque varius orci et augue pellentesque, sed elementum massa posuere. Curabitur egestas consectetur arcu, in porta lorem sagittis eu. Nulla facilisi. Sed scelerisque ligula lectus. Nulla et ligula a eros laoreet lacinia nec et ipsum. Ut sagittis sapien est, ut blandit risus laoreet at. Vestibulum vitae erat sed dolor ultricies efficitur.</p>
<% end %>