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.
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
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 %>
With data attributes (preview)
<%= render "govuk_publishing_components/components/button", {
text: "Open modal with data attributes",
data_attributes: {
toggle: "modal",
target: "modal-with-data-attributes"
}
} %>
<%= render "govuk_publishing_components/components/modal_dialogue", {
id: "modal-with-data-attributes",
data_attributes: {
gtm: "modal"
}
} 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 %>