Loading box
Wraps content that loads asynchronously. While loading is true, a spinner and overlay cover the content and statusText is announced.
- Say what’s happening in statusText, and keep it showing for at least a couple of seconds so it doesn’t flash and screen readers have time to announce it.
- Don’t disable buttons while loading: disabled buttons have poor contrast and can confuse some users. Prevent repeat submissions in your submit handler, and on the server.
- When loading ends, move focus to the result, or to the error summary if there are errors.
- If loading fails or times out, show an error and a way to continue. Don’t leave the spinner running.
Import
import { LoadingBox } from 'govuk-react/loading-box';Examples
Default
Code
Template.bind({})Partial cover
Code
Template.bind({})Loading box long
Code
Template.bind({})Short height
Code
Template.bind({})With bold text
Code
Template.bind({})Toggle
Code
{
const [loading, setLoading] = React.useState(false);
return (
<>
<Button type="button" onClick={() => setLoading((value) => !value)}>
{loading ? 'Stop loading' : 'Start loading'}
</Button>
<LoadingBox {...args} loading={loading}>
<Heading size="l">Example</Heading>
<InputField id="toggle-email-address" name="email-address" label="Email address" />
</LoadingBox>
</>
);
}Submitting a form
Code
{
const [state, setState] = React.useState<'editing' | 'sending' | 'sent'>('editing');
const sending = React.useRef(false);
const confirmation = React.useRef<HTMLHeadingElement>(null);
React.useEffect(() => {
if (state === 'sent') confirmation.current?.focus();
}, [state]);
if (state === 'sent') {
return (
<Heading size="l" ref={confirmation} tabIndex={-1}>
Details sent
</Heading>
);
}
return (
<LoadingBox loading={state === 'sending'} statusText="Sending your details" inertWhileLoading>
<form
onSubmit={(event) => {
event.preventDefault();
// Ignore repeat submissions rather than disabling the button.
if (sending.current) return;
sending.current = true;
setState('sending');
// Keep the loading state for at least a couple of seconds.
setTimeout(() => setState('sent'), 2000);
}}
>
<InputField id="form-email-address" name="email-address" label="Email address" />
<Button type="submit">Continue</Button>
</form>
</LoadingBox>
);
}API reference
LoadingBox
Wraps content that loads asynchronously. While loading is true, a spinner and overlay cover the content and statusText is announced.
- Say what’s happening in statusText, and keep it showing for at least a couple of seconds so it doesn’t flash and screen readers have time to announce it.
- Don’t disable buttons while loading: disabled buttons have poor contrast and can confuse some users. Prevent repeat submissions in your submit handler, and on the server.
- When loading ends, move focus to the result, or to the error summary if there are errors.
- If loading fails or times out, show an error and a way to continue. Don’t leave the spinner running.
| Prop | Type |
|---|---|
loadingWhether the content is loading. Shows the spinner and overlay, announces | boolean |
statusTextText announced to screen reader users while loading, and shown instead of the spinner when the user prefers reduced motion. Say what’s happening, such as “Sending your application”. | ReactNode |
inertWhileLoadingMake the content inert while loading, so users can’t interact with it or move focus into it. Focus inside the content moves to the page body, so move focus yourself when loading ends. | boolean |
spinnerColorColour of the spinner, as any CSS colour. Defaults to the text colour. | string |
backgroundColorColour of the overlay, as any CSS colour. Defaults to the page background colour. | string |
backgroundColorOpacityOpacity of the overlay, from 0 to 1. | number |
timeInLength of the fade-in, in milliseconds. | number |
timeOutLength of the fade-out, in milliseconds. | number |