Timeout modal

Overview

A timeout warning that lets users extend the amount of time they have to complete a task.

{% from "components/timeout-modal/_macro.njk" import onsTimeoutModal %}

<div style="min-height:20rem;">
    {{
        onsTimeoutModal({
            "showModalTimeInSeconds": 60,
            "redirectUrl": "#!",
            "title": "You will be signed out soon",
            "textFirstLine": "It appears you have been inactive for a while.",
            "countdownText": "To protect your information, your progress will be saved and you will be signed out in",
            "countdownExpiredText": "You are being signed out.",
            "btnText": "Continue survey",
            "minutesTextSingular": "minute",
            "minutesTextPlural": "minutes",
            "secondsTextSingular": "second",
            "secondsTextPlural": "seconds",
            "endWithFullStop": true
        })
    }}
</div>

<div style="min-height:20rem;">
  <dialog class="ons-modal ons-js-modal ons-js-timeout-modal" id="dialog" role="dialog"
    aria-labelledby="ons-modal-title" data-redirect-url="#!" data-server-session-expires-at="" data-show-modal-time="60"
    data-server-session-expiry-endpoint=""
    data-countdown-text="To protect your information, your progress will be saved and you will be signed out in"
    data-countdown-expired-text="You are being signed out." data-minutes-text-singular="minute"
    data-minutes-text-plural="minutes" data-seconds-text-singular="second" data-seconds-text-plural="seconds"
    data-full-stop="true" aria-describedby="timeout-time-remaining">
    <div class="ons-modal__content">
      <h2 id="ons-modal-title" class="ons-modal__title">You will be signed out soon</h2>
      <div class="ons-modal__body">
        <p>It appears you have been inactive for a while.</p>
        <p class="ons-js-timeout-timer" aria-hidden="true" aria-relevant="additions"></p>
        <p class="ons-js-timeout-timer-acc ons-u-vh" role="status" id="timeout-time-remaining"></p>
      </div>
      <button type="submit" class="ons-btn ons-js-modal-btn ons-u-mt-s">
        <span class="ons-btn__inner"><span class="ons-btn__text">Continue survey</span></span>
      </button>
    </div>
  </dialog>
</div>

When to use this component

Use this component when a service sets a session expiry time to protect the user’s information.

There is specific guidance on how to help users extend a session.

How to use this component

The content of the timeout modal is set using the parameters shown in the macro options table in the previous example.

You will also need to set the parameters:

• showModalTimeInSeconds with the number of seconds the modal should show for before the session expiry time (this should be at least 60 seconds)
• sessionExpiresAt with the current expiry time in ISO format on page load
• serverSessionExpiryEndpoint with a relative url to the server’s API endpoint for the component to send requests to
• redirectUrl with a url to the session timed out error page the user is directed to when the session has timed out

Server requirements

The timeout modal component requires an API endpoint that handles two request methods and returns a JSON object containing the key expires_at with a value for the session expiry time in ISO format.

1. A request to reset the expiry time

When a request using a PATCH method is received the session expiry time should be reset to the original session length from the current time, and the response should contain the new expiry time.

A request to reset the expiry time will be sent when:

• the modal is closed by the user
• the user interacts with the page in any way, for example, by moving the cursor

To efficiently handle the number of requests made when the user interacts with the page, the requests are "throttled" so only one is sent every minute, and others in the queue are cleared.

2. A request for the current expiry time

When a request using a GET method is received, the response should contain the current expiry time.

The request is made to check if the same session is being interacted with in another tab. If the expiry time has changed, the timeout will be restarted against the expiry time in the response.

A request to get the current expiry time will be sent when the following happens:

• before the modal opens
• at 20-second intervals while the modal is open

Failure responses from the server

If the response status does not have a successful 200 code, the component will handle the response as a session expiry and redirect the user to the url set in the redirectUrl parameter.

Accessibility

This component helps services meet WCAG 2.1 success criterion 2.2.1 (Timing Adjustable). This requires services to warn users before a timeout occurs and allow them to extend it.

This component and it's accessibility features are based on the GDS timeout modal prototype and research (opens in a new tab)  . We will be carrying out our own accessibility testing to validate it.

Accessibility requirements

The WCAG guidelines state:

• there should be no limit to the number of times a user can extend their session
• the timeout modal should announce the remaining time at appropriate intervals to assistive technology
• when the modal is closed the previously focused element on the page must be put back in focus

Accessibility attributes on the component’s elements

Google analytics

Optionally pass event tracking data attributes for Google Analytics by providing enableGA: true. Data attributes will be dynamically set for the following events:

• When the modal opens via timed or click event
• When the modal is closed via timed or click event
• When the modal is closed via Escape keypress

The following attributes will be set

• data-ga-category="{modalType} modal"
• data-ga-action="Modal {action} by {eventType}"
• data-ga-label="{modalType} modal {action}"

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Timeout modal’ component on GitHub (opens in a new tab)