Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modal dialogue #30

govuk-design-system opened this issue Jan 12, 2018 · 20 comments

Modal dialogue #30

govuk-design-system opened this issue Jan 12, 2018 · 20 comments


Copy link

@govuk-design-system govuk-design-system commented Jan 12, 2018

Also known as: Modal window, pop-up


A pop up window that appears over the current page and requires interaction before the user can proceed.


Services using this pattern:

  • Employers Checking Service
  • Passport renewals (timeout)

Anything else

Copy link

@ignaciaorellana ignaciaorellana commented Feb 20, 2018

I had a chat with @hannalaakso and the example component is also referenced in the Timeout warning. We recommend for now to look at both issues in the backlog.

Copy link

@owenm6 owenm6 commented Mar 1, 2018

We have updated our guidance which makes it clear to avoid modals in most cases. Timeout is one of the few cases where a modal is appropriate -

Copy link

@hannalaakso hannalaakso commented Apr 19, 2018

Here's our draft accessibility criteria for modal dialogs:

Here's a Dropbox paper article that discusses Modal dialogs:

@penx penx mentioned this issue May 2, 2018
6 of 12 tasks complete
@stevenaproctor stevenaproctor mentioned this issue Nov 26, 2018
0 of 5 tasks complete
Copy link

@davidolsan davidolsan commented Jan 14, 2019

The editable modal for backend admin course management



The modal window used by providers to enter/edit their course information while staying on the course list page.


  • Providers need to quickly update course description without leaving the inline form grid used to update all other course details, instances and qualifications.
Copy link

@kr8n3r kr8n3r commented Mar 5, 2019

accessibility review of native dialog

tldr; I’m just going to say right now that the dialog element and its polyfill are not suitable for use in production.

Copy link

@soniaturcotte soniaturcotte commented Jul 9, 2019

We use a modal on Content Publisher for inserting particular markdown (inline images/attachments) into the body textarea.

There were two main reasons that we chose a modal instead of going to another page

  • Users can add content without saving the document (Title is a required field)
  • The markdown is inserted where the user left their cursor in the content

Example of the modal:

Copy link

@colinrotherham colinrotherham commented Oct 1, 2019

We're about to test a modal dialogue to meet WCAG 2.1 Guideline 2.2 Enough Time.


All public services with session timeouts of less than 20 hours should be doing something similar, otherwise they're not meeting this bit of WCAG 2.1 here:

Success Criterion 2.2.1 Timing Adjustable
If a session is discarded after less than 20 hours, we must provide the facility to either:

  1. Turn off the timeout
  2. Adjust the timeout via a setting (make it longer)
  3. Offer to extend the timeout with at least 20 seconds notice

We'd be happy to contribute our component if it tests well.

Lots of work has been done by @alex-ju already:

Initially we're trying the alertdialog ARIA role.

This applies to #104 (Timeout warning) as well.

Copy link

@edwardhorsford edwardhorsford commented Oct 2, 2019

@colinrotherham is that 'Resume application' button active or are you using different button styles for this?

Copy link

@colinrotherham colinrotherham commented Oct 2, 2019

@edwardhorsford It's focussed due to the guidance on the alertdialog ARIA role:

Unlike regular alerts, an alert dialog must have at least one focusable control and focus must be moved to that control when the alert dialog appears. Generally alert dialogs have at least a Confirmation, Close or Cancel button that can be used to move focus to.

We'll need further testing to confirm if this bit is correctly implemented:

When the alert dialog is correctly labeled and focus is moved to a control inside the dialog, screen readers should announce the dialog's accessible role, name and optionally description before announcing the focused element.

Copy link

@joelanman joelanman commented Oct 2, 2019

@colinrotherham The screenshot says the session is due to expire in 5 minutes, and then that your session will end in 20 seconds, is that a bug? Would the content update in realtime?

Copy link

@edwardhorsford edwardhorsford commented Oct 2, 2019

@colinrotherham hmm, interesting! I might raise this on the button issue -it feels funny to land on a page with a yellow button when you've not actively focussed it.

@edwardhorsford edwardhorsford mentioned this issue Oct 2, 2019
Copy link

@colinrotherham colinrotherham commented Oct 3, 2019

@joelanman It's a typo of mine, we fixed it for the user research session! We did look at realtime countdowns, and will hopefully follow up with further research (screenshot updated).

Other solutions are very "chatty" for screen readers when it counts down every second.

Copy link

@edwardhorsford edwardhorsford commented Oct 3, 2019

@joelanman It's a typo of mine, we fixed it for the user research session! We did look at realtime countdowns, and will hopefully follow up with further research (screenshot updated).

Other solutions are very "chatty" for screen readers when it counts down every second.

@colinrotherham I think the version I worked on with Alex announced every 30 seconds from 5 mins to 60seconds, then was faster after that.

Copy link

@colinrotherham colinrotherham commented Oct 3, 2019

@edwardhorsford Yeah that’s our current plan. User testing showed one person expected a countdown.

Copy link

@colinrotherham colinrotherham commented Oct 29, 2019

Hi @hannalaakso I've put an early demo here:

Wait 5 seconds and a alertdialog modal with focus-wrapping will open.

So far tested in Chrome, Firefox, Edge and IE9 – IE11.
I'll need some polyfills adding to improve IE8 support.

Aiming to meet the principles discussed here:

All the source is loaded into too 😊

Glitch menu

Using the <dialog> component we've found lots of issues with .showModal() especially in Chrome (doesn't adjust layout on resize) and it didn't play nice with page scroll-locking.

We've worked around these and created a govukModalDialogue() component for our demo, should you want to follow a similar pattern and add this to GOV.UK Frontend.

This largely builds on the fab work of @alex-ju!

Would love to hear your thoughts.

Still to investigate

What did you mean by point 7) about preventing search?

  1. Prevent user searching in the underlying page.

We can achieve scroll locking in most browsers, but looks like an event.preventDefault() touch event hack is required for iOS to achieve the same in mobile Safari—did you look into this too?

  1. Prevent scrolling of the underlying page

Also specifically for #104 we'll look to make the text countdown (slowly at first) with aria-live in another iteration.

Copy link

@alex-ju alex-ju commented Oct 29, 2019

This largely builds on the fab work of @alex-ju!

Just to make sure the credits are given to the right people. The modal component above is a result of a twisted but apparently successful story of a prototype build by @hannalaakso and @edwardhorsford while we were working in the "Patterns and Tools team", which generated a lot of useful insights that were used a year later to inform the development of modal for Content Publisher designed by @soniaturcotte and implemented by me - although it could've been anyone from GDS doing the same work - and iterated based on user research.

Bottom line - I'm really happy to see a crystallised component as an outcome of shared work, insights and research.

Copy link

@colinrotherham colinrotherham commented Nov 5, 2019

Updated our prototype with the header + close button bar from GOV.UK Component Guide.

We did prototype a "light" version but stuck with the dark UI as it's already in use.



@hannalaakso Would you be interested in this becoming a Design System component? We've got more testing to come of course.

Copy link

@hannalaakso hannalaakso commented Nov 14, 2019

@FeyAgape, @Ash-Wilson and @colinrotherham have kindly offered to develop this into a component for the GOV.UK Design System 🎉

Copy link

@hannalaakso hannalaakso commented Nov 14, 2019

Modal component acceptance criteria

In addition to meeting the Design System contribution criteria, we have agreed that this component will meet the following criteria:

Research criteria

The contributor must:

  • have collected at least 3 different examples of modals being used in services on GOV.UK
  • have tested with a representative range of users, including those with disabilities, in a prototype or live service OR
  • be able to show that the component is clearly based on relevant user research from other organisations and best practice (in this case, the component would be published as experimental)

Design criteria

The modal component must:

  • be usable on any screen size
  • allow users to complete their task if JavaScript is not available (we should explore different situations this could happen in and try to cover them in guidance. Component should support these different use cases.)
  • refocus last focused element when modal is closed
  • close using ESC - this should probably be opt-in
  • make background non-actionable
  • make sure long content in modal is scrollable
  • have a Close / X button
  • optional: We should explore what should happen when the modal is open and the user presses browser back button (more pertinent to users on mobile)

Guidance criteria

The component guidance (example of guidance) must:

  • follow the GOV.UK Design System content pattern
  • provide examples of common use cases
  • describe what research has been done and what still needs to be done
  • follow the GOV.UK style guide
  • describe the appropriate behaviour when JavaScript is not available, taking into account the use case

Coding criteria

The modal component must:

Accessibility criteria

  • must meet WCAG 2.1 AA guidelines
  • not depend on colour to communicate information
  • handle cases where user changes their default colours
  • be focusable with a keyboard (If an element eg. button triggers the dialog, that element must also be keyboard focusable.)
  • Inform user that an alert dialog has opened
  • Constrain focus to dialog
  • Return focus to element that had focus before the dialog was invoked.
  • Be possible to close. Be clear how to close. Examples of ways to close are pressing Esc and a close button.
  • Underlying page content must not look actionable.
  • Prevent scrolling of the underlying page.
  • Should always be visible - regardless of scrolling, screen size or orientation changes
  • the controls must be large enough to tap accurately with one finger
  • it must be possible to activate the controls using voice commands (see Coding criteria).
  • the contrast between the modal text label and its background must meet (or exceed) a ratio of 4.5:1
  • the markup must validate against HTML5 validator
  • the content must be in a logical order in the source code

Where multiple modals are open, above criteria apply to top-most one.

Copy link

@mattandrews mattandrews commented Nov 19, 2019

Just wanted to jump in here to say we're planning to use this component on – we have a session timeout which we want to warn users about and hoped there'd be an existing GDS pattern!

I took the code from the repo here and modified it a little for our purposes – one change which might be useful generally is something to close any existing modals when opening a new one? In our case we show one modal to warn the timeout is approaching, then a second one to tell the user they've been logged out. I added some code here for a basic implementation of this, plus some changes to allow for dialogs without close buttons. Thank you for the hard work here everyone – we'll keep an eye on this component if/when it becomes an official part of the Design System!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Linked pull requests

Successfully merging a pull request may close this issue.

None yet