Skip to main content
Components

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.

PropType
loading

Whether the content is loading. Shows the spinner and overlay, announces statusText, and sets aria-busy on the content.

boolean
statusText

Text 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
inertWhileLoading

Make 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
spinnerColor

Colour of the spinner, as any CSS colour. Defaults to the text colour.

string
backgroundColor

Colour of the overlay, as any CSS colour. Defaults to the page background colour.

string
backgroundColorOpacity

Opacity of the overlay, from 0 to 1.

number
timeIn

Length of the fade-in, in milliseconds.

number
timeOut

Length of the fade-out, in milliseconds.

number