GrLoading

By default the overlay lies on the nearest positioned ancestor — that is the loading of a piece of the page. fullscreen covers the whole screen: that is loading at the level of the application.

The directive chooses the mode itself: target = document.body → fullscreen, otherwise inline. To a container with position: static it temporarily gives relative, and to a container with rounding overflow: hidden, so that the blurred backdrop does not come out of the rounded shape.

delay (ms) postpones the showing. A request that answered faster than the delay does not show the overlay at all — flickering is more irritating than the absence of an indicator.

<GrLoading v-if="pending" :delay="200" />

The countdown starts from the mounting, that is, from the moment the loading started. While it is running, the content is not blocked: otherwise a fast request would silently freeze the form.

The overlay is a role="status" with aria-live="polite": the caption is read by a screen reader at the moment it appears, without interrupting the user.

Covering it visually is not enough: without blocking, the tab goes into a form that is no longer visible, and a screen reader reads it as an ordinary one. At the moment of showing, the directive therefore declares the container aria-busy="true" and gives inert to its other children — the subtree as a whole drops out of the tab order, out of pointer events and out of the accessibility tree. On closing, inert is removed only from what it set itself, and the focus returns to where it was if the user has not moved it themselves.

The declarative <GrLoading> does not dispose of its neighbours — it does not know them. If blocking is needed on the same container, take the directive.

There is deliberately no focus trap inside the overlay: there is nothing to trap in it, and the inert on the neighbours covers the task as a whole.

The full-screen mode sits on the --gr-z-loading token (1150) — above the modals, because it blocks the whole application, and below the toasts, so as not to hide a notification about a background error. The inline mode has nothing to do with the scale: z-10 is the order inside its own container.

zIndexVar replaces the layer variable with one of your own — an escape hatch of the same kind as in useFloating. The component does not accept a raw number: see docs/z-index.md.

The dimming under the panel is the --gr-overlay-bg role of the theme, the same one GrModal and GrDrawer use: a loading overlay has to look like the other modal layers and to change density together with the theme.

The background prop sets a background-color of your own and cancels the scrim entirely — it is needed when the overlay lies on an already dimmed surface.

spinnerSize and spinnerTone go through GrIcon — the scale of the icons and the text tokens rather than pixels in the markup. spinner replaces the icon itself, and animated switches the rotation off.

The slot replaces the content of the panel as a whole — progress with percentages, a button to cancel a long operation:

<GrLoading>
  <GrProgressBar :value="percent" class="w-48" />
  <GrButton size="xs" variant="outline" @click="abort">Cancel</GrButton>
</GrLoading>

The caption comes from the locale by default (gr.loading.defaultText); text sets one of your own, and an empty string removes it entirely.

const controller = createLoading({ target: '#report', text: 'Computing the report', delay: 200 })
controller.setText('Almost done')
controller.close()

v-loading accepts either a boolean or an object of options (the same as the component’s, plus target and fullscreen). Changing target or the mode recreates the overlay, everything else is updated in place.