Page Preloader

A full-screen loading overlay, meant for route transitions and first-load waits. It renders fixed inset-0 z-50 inside a <Teleport to="body">, so it covers the whole viewport no matter where you put the component in your tree — including inside a card or a dialog.

Two visual treatments: bar (default) shows a UProgress plus a percentage, spinner shows a rotating i-lucide-loader-2 icon plus the same percentage. Both sit on a translucent card over a blurred black backdrop, and the whole overlay cross-fades in and out over 250ms via AnimatePresence.

Usage

Bind loading to whether your operation is still running, and drive progress yourself — the component renders state, it never fetches anything. v-model:loading is the intended binding, so the backdrop click works out of the box.

<template>
  <div class="flex w-full max-w-md flex-col gap-4">
    <div class="flex items-center gap-3">
      <USwitch
        v-model="loading"
        label="Loading"
      />
      <USelect
        v-model="variant"
        :items="['bar', 'spinner']"
        class="w-28"
      />
    </div>

    <div class="flex h-24 items-center justify-center rounded-2xl border border-default bg-default text-sm text-muted">
      The overlay teleports to body, so it covers this card too. Click anywhere on
      it to dismiss — that emit is the only way out.
    </div>

    <UProgress
      :model-value="progress"
      :max="100"
      size="sm"
    />

    <MPagePreloader
      v-model:loading="loading"
      :progress="progress"
      :variant="variant"
    />
  </div>
</template>

<script setup lang="ts">
const loading = ref(false)
const variant = ref<'bar' | 'spinner'>('bar')
const progress = ref(0)

let timer: ReturnType<typeof setInterval> | undefined

watch(loading, (value) => {
  if (timer) {
    clearInterval(timer)
    timer = undefined
  }
  if (value) {
    progress.value = 0
    timer = setInterval(() => {
      progress.value = Math.min(100, progress.value + 4)
      if (progress.value >= 100) {
        loading.value = false
      }
    }, 60)
  }
})

onBeforeUnmount(() => {
  if (timer) clearInterval(timer)
})
</script>

Customize

Props

Events

UI

This component's theme exposes the slots below. Override any of them per instance with the ui prop, or app-wide under ui.pagePreloader in app.config.ts.

Accessibility

The overlay applies no ARIA at all: no role, no aria-modal, no aria-label, and the percentage sits in a bare <span> with no live region. Opening it does not move focus, so a keyboard user keeps their place in the page behind the overlay while the visual blocks everything.

If you use it for a blocking operation, wrap it yourself:

<div
  role="alertdialog"
  aria-modal="true"
  :aria-label="`Loading, ${Math.round(progress)} percent`"
>
  <MPagePreloader v-model:loading="loading" :progress="progress" />
</div>

Keyboard users have no way out either: there is no Escape handler and nothing inside the overlay is focusable, so Tab stays in the content behind it.

There is also no prefers-reduced-motion check — the 250ms fade and the spinner's infinite rotation both run regardless. The spinner is the worse of the two: an indefinitely rotating icon is the classic vestibular trigger, so prefer variant="bar" if motion is a concern.

Performance

• The overlay is teleported to body, so mounting it depends on no layout in the subtree that declared it — but scoped styles in your page are not applied to it either.
• AnimatePresence keeps the overlay mounted through its 250ms exit before removing it, so there is briefly one extra full-viewport element during teardown.
• z-50 is the stacking level. A modal with a higher z-index renders above the preloader, which is usually the wrong order for a blocking overlay.
• backdrop-blur-sm on both the backdrop and the card is a real per-frame cost on low-end GPUs, for as long as the overlay is up.
• Every progress change re-renders the Math.round(progress) label, so ticking progress at animation rate is fine but writing it in a requestAnimationFrame loop at full display rate is wasted work.