Skip to main content

LoadingOverlay

Focuses the user's attention on one task or piece of information.

github
View source code
figma
View design
Tip

For usability reasons, the code examples on this page are not editable. However, they can still be copied and pasted into your project.

import { LoadingOverlay } from '@uhg-abyss/web/ui/LoadingOverlay';
    () => {
      const [isLoading, setLoading] = useState(false);
      const [isOpen, setIsOpen] = useState(false);
    

      const { setCountdownTime } = useCountdown({
        onCompleted: () => {
          setLoading(false);
          setIsOpen(true);
        },
      });
    

      const triggerLoading = () => {
        setLoading(true);
        setCountdownTime(3000);
      };
    

      const handleClose = () => {
        setIsOpen(false);
      };
    

      return (
        <LoadingOverlay
          loadingTitle="Please Wait"
          loadingMessage="Retrieving Information."
          ariaLoadingLabel="Example loading ARIA label"
          statusTitle="Status update"
          statusMessage="Sample message..."
          isLoading={isLoading}
          isOpen={isOpen}
          isDismissable
          onClose={handleClose}
        >
          <Card
            css={{
              'abyss-card-root': {
                height: 300,
                display: 'flex',
                justifyContent: 'center',
                alignItems: 'center',
                backgroundColor: '$web.semantic.color.surface.container.tertiary',
              },
            }}
          >
            <Button onClick={triggerLoading}>Open LoadingOverlay</Button>
          </Card>
        </LoadingOverlay>
      );
    };

    Usage​

    There are two main states to LoadingOverlay: the loading state and the loaded state.

    • In the loading state (when isLoading is set to true), a loading spinner will appear on the left, and the loadingTitle and loadingMessage props will be used as the text next to it.
    • Once loading has completed (when isLoading is set to false), the display changes: the statusIcon prop is used to create an icon on the left to reflect the application state after the load (ex. an error icon if something went wrong, or a success icon if data was submitted), and the statusTitle and statusMessage props will be used as the text next to it. In this state, the overlay can be closed when the isDismissable prop is set to true.

    useOverlay​

    Using the useOverlay hook allows you to open the overlay and pass data into it.

    useState​

    Use the useState hook to set the open and loading states of the loading overlay.

    Loading title​

    Use the loadingTitle prop to set the title of the loading overlay when it is in the loading state.

    Loading message​

    Use the loadingMessage prop to set the description of the loading overlay when it is in the loading state.

    Status title​

    Use the statusTitle prop to set the title of the loading overlay when loading has completed.

    Status message​

    Use the statusMessage prop to set the description of the loading overlay when loading has completed.

    Status icon​

    Use the statusIcon prop to set the icon that will be displayed when loading has completed. Possible options are success, error, warning, and info. The default is info. You can hide the icon with the hideIcon prop.

    isDismissable​

    Use the isDismissable prop to determine whether the overlay can be closed after loading is complete. Use this prop with the useState hook if there are situations where the user can take another action after dismissing the overlay. The default is false. You may want to set it to false in cases such as when a widget fails to load and cannot be used. The default is false.

    isOpen​

    Use the isOpen prop to set whether the overlay is open or not. Use this prop with the useState hook to change the overlay between open and closed. The default is false.

    isLoading​

    Use the isLoading prop to set whether the overlay is loading or not. Use this prop with the useState hook to set the loading state based on the status of the rest of your application. The default is false.

    onClose​

    Use the onClose prop to set a function that will be executed when the loading overlay is closed.

    LoadingOverlay Props​

    Name
    Type
    		DefaultA11yDescription
    ariaLoadingLabel
    string | undefined
    'Loading'
    The accessible label announced to screen readers for the spinner while the overlay is loading.
    children
    string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
    The children of LoadingOverlay component
    className
    string | undefined
    CSS class name to apply to each element within the component
    css
    CSSProperties | Partial<Record<"abyss-alert-icon" | "abyss-loading-overlay-dialog" | "abyss-loading-overlay-root" | "abyss-loading-overlay-close-button" | "abyss-loading-overlay-close-icon" | ... 9 more ... | "abyss-loading-overlay-status-message", CSSProperties>> | undefined
    Object containing CSS styling to apply; uses the classes listed in the "Integration" tab of the component's documentation
    See CSS Prop Styling for more information
    data-testid
    string | undefined
    Suffix used to create a unique ID used for automated testing
    See Component Testing for more information
    hiddenFrom
    Breakpoint | undefined
    When defined, the component is hidden once the screen width reaches the specified breakpoint.
    hideIcon
    boolean | undefined
    false
    If true , it hides the icon
    isDismissable
    boolean | undefined
    false
    If true , the overlay is dismisable
    isLoading
    boolean | undefined
    false
    If true , the overlay is loading
    isOpen
    boolean | undefined
    false
    If true , the overlay is opened
    loadingIcon
    string | number | bigint | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal | Promise<...> | null | undefined
    The icon that will be displayed inside LoadingSpinner
    loadingMessage
    string | undefined
    The message announced to screen readers via the loading overlay's role="alert" region.
    loadingTitle
    string | undefined
    The title announced to screen readers via the loading overlay's role="alert" region.
    model
    string | undefined
    The model of LoadingOverlay component
    onClose
    (() => void) | undefined
    The onClose function of LoadingOverlay component
    slotProps
    Partial<Record<ToSlotKey<{ root: LeafSlotDef<"div", undefined>; overlay: LeafSlotDef<"div", undefined>; dialog: LeafSlotDef<"div", undefined>; closeButton: LeafSlotDef<...>; ... 10 more ...; statusMessage: LeafSlotDef<...>; }, "loading-overlay">, SlotPropsLeafValue>> | undefined
    Props to pass to individual internal slots of the LoadingOverlay component.
    See slotProps for more information
    statusIcon
    "error" | "info" | "warning" | "success" | undefined
    'info'
    The icon that will be displayed when loading is completed
    statusMessage
    string | undefined
    The message that will be displayed when loading is completed
    statusTitle
    string | undefined
    The title that will be displayed when loading is completed
    visibleFrom
    Breakpoint | undefined
    When defined, the component is hidden until the screen width reaches the specified breakpoint.
    width
    string | number | undefined
    '80%'
    The width of loading dialog

    LoadingOverlay Classes​

    Class NameDescription
    .abyss-alert-iconLoadingOverlay status icon element
    .abyss-loading-overlay-close-buttonLoadingOverlay close button element
    .abyss-loading-overlay-close-iconLoadingOverlay close icon element
    .abyss-loading-overlay-dialogLoadingOverlay dialog element
    .abyss-loading-overlay-loading-bodyLoadingOverlay loading body element
    .abyss-loading-overlay-loading-contentLoadingOverlay loading content element
    .abyss-loading-overlay-loading-messageLoadingOverlay loading message element
    .abyss-loading-overlay-loading-titleLoadingOverlay loading title element
    .abyss-loading-overlay-overlayLoadingOverlay overlay element
    .abyss-loading-overlay-rootLoadingOverlay root element
    .abyss-loading-overlay-status-bodyLoadingOverlay status body element
    .abyss-loading-overlay-status-contentLoadingOverlay status content element
    .abyss-loading-overlay-status-icon-wrapperLoadingOverlay status icon wrapper element
    .abyss-loading-overlay-status-messageLoadingOverlay status message element
    .abyss-loading-overlay-status-titleLoadingOverlay status title element

    Simple LoadingOverlay​

    A basic LoadingOverlay, when isDismissable = false, is used to indicate to the user that a process is occurring during which time they may not interact with any elements underneath the overlay. The overlay is coded as an Alert, meaning that most screen readers will announce the overlay once it renders. By default, the LoadingOverlay contains no interactive elements

    Adheres to the Alert WAI-ARIA design patternopens in a new window.

    The Alert Exampleopens in a new window provided by W3.org demonstrates the Alert Pattern.

    LoadingOverlay Alert Dialog​

    LoadingOverlay becomes an interactive alert dialog when isDismissable = true. The only interactions are to move focus through, or close the dialog window.

    This follows the WAI-ARIA Alert Dialog Exampleopens in a new window and has limited keyboard interaction to close the overlay using the Close button or Escape.

    Table of Contents