The loading overlay displays an ongoing process within a block.
When you need to clearly show that a block is loading or a process is running. Before adding a loader overlay, clarify the loading time.
The spinner overlay is a temporary state of a block. It appears in response to a user action (for example, clicking a submit button in a form) or a system process. After the process completes, the overlay and spinner disappear.
Elements behind the overlay must not be accessible for focus, selection, or clicking.
Semi-transparent overlay, spinner, main text. The default text is "Loading"; it is recommended to choose the text individually. Do not use single-word "Loading" text with an enlarged spinner.
The system prevents focusing on form elements covered by the overlay. The content behind the overlay cannot be selected or clicked either, and screen readers skip its elements. The overlay itself stays available: its text can be selected, and buttons and links on it, such as Cancel or a link to help, work as usual. Screen readers do not announce the overlay when it appears, so announce the loading separately, for example with LiveAnnouncer from @angular/cdk/a11y.
Once the overlay is hidden, focus returns to the element that had it before the overlay appeared, unless the user has moved it to another element. To move focus to another element behind the overlay after loading, do it once the overlay is hidden, for example in afterNextRender.
If a request completes quickly, the spinner only flashes, which looks like a glitch. Show the overlay after 500 ms: a fast request completes earlier, and the overlay never appears. Once the overlay has appeared, keep it on screen for at least 300 ms.
Delay only the indicator: block a repeated action immediately, for example by disabling the button. Use the kbqDelayLoadingIndicator operator for the delay.
The delay does not prevent content from jumping. To keep content in place, keep the previous data until the new data arrives, reserve space for the block, or show a skeleton: it appears immediately, without a delay.
If an overlay covers only part of the screen, its edge remains visible. The transition looks seamless when the overlay color matches the container surface. Use the surface attribute to select the appearance.
If surface is not set, the deprecated transparent and card attributes select a surface: transparent="true" corresponds to surface="bg", transparent="false" to surface="solid", and card="true" to surface="card". The card attribute takes precedence over transparent.
surface value | Description |
|---|---|
bg | Primary background |
bg-secondary | Secondary background |
bg-tertiary | Tertiary background |
card | Dropdown menus, modal windows, and cards |
solid | Opaque backdrop |
Content behind the overlay becomes barely visible, as if hidden in fog. The interface remains recognizable while loading continues, but the main actions are temporarily unavailable.
The overlay blends seamlessly with the background, leaving no visible boundary around its edges. Matching the overlay color to the surface keeps the container connected to the surrounding interface.
Content behind the overlay becomes barely visible, as if hidden in fog. The interface remains recognizable while loading continues, but the main actions are temporarily unavailable.
The overlay blends seamlessly with the background, leaving no visible boundary around its edges. Matching the overlay color to the surface keeps the container connected to the surrounding interface.
Content behind the overlay becomes barely visible, as if hidden in fog. The interface remains recognizable while loading continues, but the main actions are temporarily unavailable.
The overlay blends seamlessly with the background, leaving no visible boundary around its edges. Matching the overlay color to the surface keeps the container connected to the surrounding interface.
Content behind the overlay becomes barely visible, as if hidden in fog. The interface remains recognizable while loading continues, but the main actions are temporarily unavailable.
The overlay blends seamlessly with the background, leaving no visible boundary around its edges. Matching the overlay color to the surface keeps the container connected to the surrounding interface.
Content behind the overlay becomes barely visible, as if hidden in fog. The interface remains recognizable while loading continues, but the main actions are temporarily unavailable.
The overlay blends seamlessly with the background, leaving no visible boundary around its edges. Matching the overlay color to the surface keeps the container connected to the surrounding interface.
The overlay covers the full width and height of the container it is displayed over. Padding from the overlay edges is 10% of its width. Maximum width of the text and caption under the spinner is 480px.
Center alignment with optical compensation is available: the top offset should be smaller than the bottom. By default, the compensation height equals 40% of the block height comprising the loading indicator and captions.
Fixed top-offset alignment is also available (72px by default).
When it is necessary to display the loading process on the entire page, an enlarged spinner is used. Do not use single-word "Loading" text with an enlarged spinner.
The component size is set using the size attribute.