Dialogs are pop-up elements that appear over a page to show important content or options.
The Dialog component renders its inner contents within a modal dialog region while the rest of the page is darkened and inaccessible, which the end user can dismiss through a variety of methods.
When to use this component
Dialogs are useful when you need to highlight content or important tasks, such as confirming an action or filling out a form. They work well for showing focused content without distracting from the rest of the page. Use dialogs sparingly to avoid overwhelming users or interrupting their experience unnecessarily.
Examples in GOSS products
- Image and Image Gallery inlines that show larger versions of the image rendered within the body content
- The cookie policy configured to render as a dialog
Accessibility considerations
The dialog component also works without JavaScript, using a system like other show/hide features based on element ID links. To use this, the dialog trigger should update the page URL with a fragment, alongside the existing JavaScript method.
General notes
The no-JS fallback method doesn't support multiple dialogs, so stacked dialogs should be treated as a progressive enhancement and not relied on.
An optional attribute has been added to make dialogs non-dismissible by standard controls, useful for cases where users must interact with the dialog before continuing. If set to 'true,' the dialog can only be closed from another trigger, unless the intent is to trap the user indefinitely.
With JS, the dialog system now ensures the most recently interacted-with dialog appears on top when multiple are open.
Basic dialog
A dialog with no additional configuration options.
The title can be changed to be a heading element e.g. H2/H3 based on your structural needs.
Dialog title
<div id="dialog_basic" class="dialog dialog--hidden dialog--nojs" data-dismissible="true">
<div class="dialog__content" role="dialog" aria-labelledby="dialog_basic_header" style="max-width: 500px">
<h2 id="dialog_basic_header" class="dialog__header">Dialog title</h2>
<div class="dialog__body">
Dialog content
</div>
<button class="dialog__close" aria-label="Close dialog title"></button>
</div>
<a class="dialog__closefallback" href="#">
<span class="dialog__closefallbackouter" style="max-width: 500px">
<span class="dialog__closefallbackinner">
<span class="accessibility">Close dialog title</span>
</span>
</span>
</a>
</div>
<button onclick="gi.dialog('dialog_basic').open()" class="btn" aria-label="Open basic dialog">
<span class="btn__text">Open basic dialog</span>
</button><comp:dialog id="dialog_basic" title="Dialog title">
Dialog content
</comp:dialog>
<comp:button text="Open basic dialog" onclick="gi.dialog('dialog_basic').open()" label="Open basic dialog"/>@{
var settings = new DialogSettings()
{
Id = "dialog_basic",
Title = "Dialog title"
};
}
@{
using (Html.Dialog(settings))
{
<p>Dialog content</p>
}
}
<button onclick="gi.dialog('dialog_basic').open()" class="btn" aria-label="Open Basic dialog title">
<span class="btn__text">Open basic dialog</span>
</button>Dismissible dialog
A dialog with the dismissible attribute set to 'true'.
data-dismissible="true"
The dismissible attribute makes a dialog easy to close with standard actions like clicking outside it, providing a user-friendly experience. It ensures flexibility and control, allowing users to exit the dialog without unnecessary steps.
Dialog title
<div id="dialog_dismissible" class="dialog dialog--hidden dialog--nojs" data-dismissible="true">
<div class="dialog__content" role="dialog" aria-labelledby="dialog_dismissible_header" style="max-width: 500px">
<h2 id="dialog_dismissible_header" class="dialog__header">Dialog title</h2>
<div class="dialog__body">
Dialog content
</div>
<button class="dialog__close" aria-label="Close dialog title"></button>
</div>
<a class="dialog__closefallback" href="#">
<span class="dialog__closefallbackouter" style="max-width: 500px">
<span class="dialog__closefallbackinner">
<span class="accessibility">Close dialog title</span>
</span>
</span>
</a>
</div>
<button onclick="gi.dialog('dialog_dismissible').open()" class="btn" aria-label="Open dismissible dialog">
<span class="btn__text">Open dismissible dialog</span>
</button><comp:dialog id="dialog_dismissible" title="Dialog title" dismissible="true">
Dialog content
</comp:dialog>
<comp:button text="Open dismissible dialog" onclick="gi.dialog('dialog_dismissible').open()" label="Open dismissible dialog"/>@{
var settings = new DialogSettings()
{
Id = "dialog_dismissible",
Title = "Dialog title"
Dismissible = true
};
}
@{
using (Html.Dialog(settings))
{
<p>Dialog content</p>
}
}
<button onclick="gi.dialog('dialog_dismissible').open()" class="btn" aria-label="Open dismissible dialog title">
<span class="btn__text">Open dismissible dialog</span>
</button>Change dialog width
A dialog with the max width attribute set to '1000px'.
data-gi-dialog-maxwidth="1000"
The max-width attribute controls the dialog's size, ensuring it adapts to different content. It allows designers to set clear boundaries, preventing overly wide dialogs that could overwhelm the user or look inconsistent.
Dialog title
<div id="dialog_width" class="dialog dialog--hidden dialog--nojs" data-dismissible="true">
<div class="dialog__content" role="dialog" aria-labelledby="dialog_width_header" style="max-width: 1000px">
<h2 id="dialog_width_header" class="dialog__header">Dialog title</h2>
<div class="dialog__body">
Dialog content
</div>
<button class="dialog__close" aria-label="Close dialog title"></button>
</div>
<a class="dialog__closefallback" href="#">
<span class="dialog__closefallbackouter" style="max-width: 500px">
<span class="dialog__closefallbackinner">
<span class="accessibility">Close dialog title</span>
</span>
</span>
</a>
</div>
<button onclick="gi.dialog('dialog_width').open()" class="btn" aria-label="Open different width dialog">
<span class="btn__text">Open different width dialog</span>
</button><comp:dialog id="dialog_width" title="Dialog title" maxWidth="1000">
Dialog content
</comp:dialog>
<comp:button text="Open different width dialog" onclick="gi.dialog('dialog_width').open()" label="Open different width dialog"/>@{
var settings = new DialogSettings()
{
Id = "dialog_width",
Title = "Dialog title"
Dismissible = true,
Width = 1000
};
}
@{
using (Html.Dialog(settings))
{
<p>Dialog content</p>
}
}
<button onclick="gi.dialog('dialog_width').open()" class="btn" aria-label="Open different width dialog title">
<span class="btn__text">Open different width dialog</span>
</button>Dialog content example
A dialog with complex content within the dialog's body.
The dialog keeps the focus within its content by looping the tabbing, so users can't accidentally tab outside of it. This ensures that users stay within the dialog until it is closed, making navigation easier and more accessible.
Dialog title
This is an example of a dialog with complex content:
Here is some additional copy to explain the dialog content further. You can add more text here as needed to provide context or instructions for the user.
<div id="dialog_complex" class="dialog dialog--hidden dialog--nojs" data-dismissible="true">
<div class="dialog__content" role="dialog" aria-labelledby="dialog_complex_header" style="max-width: 1000px">
<h2 id="dialog_complex_header" class="dialog__header">Dialog title</h2>
<div class="dialog__body">
<p>This is an example of a dialog with complex content:</p>
<ul>
<li><a href="https://example.com" target="_blank">Link to Example 1</a></li>
<li><a href="https://example.com" target="_blank">Link to Example 2</a></li>
<li><a href="https://example.com" target="_blank">Link to Example 3</a></li>
</ul>
<p>Here is some additional copy to explain the dialog content further. You can add more text here as needed to provide context or instructions for the user.</p>
</div>
<button class="dialog__close" aria-label="Close dialog title"></button>
</div>
<a class="dialog__closefallback" href="#">
<span class="dialog__closefallbackouter" style="max-width: 500px">
<span class="dialog__closefallbackinner">
<span class="accessibility">Close dialog title</span>
</span>
</span>
</a>
</div>
<button onclick="gi.dialog('dialog_complex').open()" class="btn" aria-label="Open complex content dialog">
<span class="btn__text">Open complex content dialog</span>
</button><comp:dialog id="dialog_complex" title="Dialog title" maxWidth="1000">
<p>This is an example of a dialog with complex content:</p>
<ul>
<li><a href="https://example.com" target="_blank">Link to Example 1</a></li>
<li><a href="https://example.com" target="_blank">Link to Example 2</a></li>
<li><a href="https://example.com" target="_blank">Link to Example 3</a></li>
</ul>
<p>Here is some additional copy to explain the dialog content further. You can add more text here as needed to provide context or instructions for the user.</p>
</comp:dialog>
<comp:button text="Open complex content dialog" onclick="gi.dialog('dialog_complex').open()" label="Open complex content dialog"/>@{
var settings = new DialogSettings()
{
Id = "dialog_complex",
Title = "Dialog title"
Dismissible = true,
};
}
@{
using (Html.Dialog(settings))
{
<p>This is an example of a dialog with complex content:</p>
<ul>
<li><a href="https://example.com" target="_blank">Link to Example 1</a></li>
<li><a href="https://example.com" target="_blank">Link to Example 2</a></li>
<li><a href="https://example.com" target="_blank">Link to Example 3</a></li>
</ul>
<p>Here is some additional copy to explain the dialog content further. You can add more text here as needed to provide context or instructions for the user.</p>
}
}
<button onclick="gi.dialog('dialog_complex').open()" class="btn" aria-label="Open different width dialog title">
<span class="btn__text">Open different width dialog</span>
</button>Share this page
