DEV Community: Navid jaberi

Why Your Loading Spinner Flashes, and the Two Numbers That Fix It in Vue

Navid jaberi — Wed, 14 Oct 2026 08:43:55 +0000

You click a button, the request takes 80ms, and a spinner appears for a single frame. It doesn't look fast. It looks broken.

Some context first. I started vue-smart-loading-kit because of skeletons. In my Vue projects I used Vuetify's skeleton loader, but I couldn't get the colors and animation I wanted, and its presets didn't match a lot of my real layouts. I kept hand-writing CSS to make a skeleton look like the actual component.

At some point I asked myself: why not turn the real layout itself into its skeleton, with CSS only and without touching the DOM? That became v-skeleton, which I wrote about in my previous article. A reader there spotted a bug with SVG icons in the comments, and I shipped the fix in 0.3.4 the same day.

But a skeleton that looks right is only half of a good loading state. The other half is timing.

The naive version

<Spinner v-if="loading" />

The loader follows loading exactly. That's the problem: users don't care how long loading was true. They care about what they saw. An 80ms request shows a spinner for 80ms, which is one flash.

Adding a delay creates a new problem

The obvious fix is to wait a little before showing the loader. Say 200ms. Now the 80ms request shows nothing, which is what we want.

But take a request that lasts 250ms. The spinner appears at 200ms and disappears at 250ms: it's on screen for 50ms. The flash is back, just later. I call that a blink.

Two numbers

When I built SmartLoader, the timing came down to two numbers:

delay (200ms): a load must last this long before any loader appears. Fast loads show nothing at all.
minDuration (500ms): once a loader is visible, it stays at least this long. It never just blinks.

One more rule: if loading starts again while the loader is still up, the loader simply stays.

Here's what that does to a few loads:

The load takes	What the user sees
120ms	No loader. The content just appears.
300ms	Loader from 200ms to 700ms
2s	Loader from 200ms to 2s

A simplified version of the idea

This isn't the package's code, just the core logic in a few lines:

import { ref, watch, onScopeDispose, type Ref } from 'vue'

export function useDelayedLoadingSimple(
  loading: Ref<boolean>,
  delay = 200,
  minDuration = 500,
) {
  const show = ref(false)
  let delayTimer: ReturnType<typeof setTimeout> | undefined
  let minTimer: ReturnType<typeof setTimeout> | undefined
  let shownAt = 0

  watch(
    loading,
    (isLoading) => {
      if (isLoading) {
        clearTimeout(minTimer) // restarted: keep the loader if it's up
        if (show.value) return
        delayTimer = setTimeout(() => {
          show.value = true
          shownAt = Date.now()
        }, delay)
      } else {
        clearTimeout(delayTimer) // done before the delay: never show
        if (!show.value) return
        const remaining = minDuration - (Date.now() - shownAt)
        minTimer = setTimeout(() => (show.value = false), Math.max(0, remaining))
      }
    },
    { immediate: true },
  )

  onScopeDispose(() => {
    clearTimeout(delayTimer)
    clearTimeout(minTimer)
  })

  return show
}

In the package this is useDelayedLoading. loading and both options can be refs or getters:

import { useDelayedLoading } from 'vue-smart-loading-kit'

const showLoader = useDelayedLoading(loading, { delay: 200, minDuration: 500 })

Timing is only half of it

A real loading state needs more than a boolean, so SmartLoader wraps the content and also:

keeps the content's height while the loader stands in for it, so the page below doesn't jump;
sets aria-busy="true" as soon as loading starts, and announces a label to screen readers while the loader is visible;
shows an error with a Try again button that emits retry. During a retry the error stays on screen until the loader appears, so nothing flashes in between.

<SmartLoader :loading="loading" :error="error" @retry="loadUsers">
  <UserList :users="users" />
</SmartLoader>

It has three modes:

Mode	While loading	Good for
`replace` (default)	Swaps the content for a skeleton	First load, no data yet
`overlay`	Keeps the content dimmed and inert, with a spinner on top	Refreshing data, submitting forms
`skeletonize`	Turns the content into its own skeleton with `v-skeleton`	First load with placeholder data

Trade-offs, and what else is out there

minDuration isn't free. If a request takes 250ms, the data is ready at 250ms but the loader stays until 700ms. I think a steady half second reads better than a 50ms blink, but it's a trade-off, which is why both numbers are props you can change.

The idea isn't new either. In React, spin-delay does the same thing with different defaults (500ms delay, 200ms minimum). There's no single right pair of numbers. It depends on how fast your API usually is and how heavy your loader looks.

A few related tools solve other parts of the problem:

CSS animation-delay can hide a loader for the first 200ms, but it can't keep one on screen after loading turns false, because the element is removed right away.
Vue's <Suspense> (still experimental) has a timeout prop that delays the fallback while content is being replaced, but there's no minimum duration, and it only covers async components.
Keeping the old data on screen while new data loads (stale-while-revalidate, or SmartLoader's overlay mode) is often better than any loader when you're refreshing.

When you can avoid a loader entirely, do that. SmartLoader is for the cases where you can't.

Takeaway

If you remember one thing: don't bind a loader directly to loading. Put a short delay in front of it and a minimum duration behind it.

The package is on npm as vue-smart-loading-kit, and the live demo lets you play with both numbers.

GitHub: https://github.com/navidjaberi/vue-smart-loading-kit
I write about Vue and frontend on LinkedIn

What delay do you use for loaders in your apps, or do you show them right away?

I built a Vue directive that turns your real component into its own skeleton

Navid jaberi — Sat, 03 Oct 2026 09:22:13 +0000

Skeleton loaders have a maintenance problem. You build a second version of every component by hand: a grey circle where the avatar goes, three bars where the text goes. Then someone adds a badge to the real card, and the skeleton quietly stops matching.

I wanted the skeleton to come from the component itself. So I built v-skeleton, a directive in vue-smart-loading-kit:

<UserCard v-skeleton="loading" :user="user" />

While loading is true, every line of text becomes a bar, images and buttons become solid blocks, and borders and spacing stay exactly as they are. When loading ends, the real content is back. Try it in the live demo (Skeletonize page, tick "loading").

This post is about how it works, and about the bugs that only showed up because of how I tested it.

The rule: never change the DOM

The obvious approach is to measure the real elements and render placeholder boxes over them. That needs JavaScript on every render, and every resize, and it fights with your layout.

I took the opposite route. The directive only toggles a class, a few CSS variables and two attributes on the element:

<article class="card vslk-skeletonize vslk-skeletonize--shimmer"
         style="--vslk-sk-base: …; --vslk-sk-hi: …"
         inert aria-hidden="true">

Everything else is CSS. No element is added, removed or resized, so nothing can move. That turned out to be the most important design decision, and the hardest to keep.

Hiding text without breaking borders

My first version hid text with color: transparent. It looked right until a code review found that it also erased every border, divider and icon that uses currentColor. A card with a 1px solid currentColor border lost its border.

The fix is a property most people never touch:

.vslk-skeletonize * {
  -webkit-text-fill-color: transparent !important;
}

text-fill-color paints only the glyphs. color, and everything that inherits it through currentColor, keeps its real value.

One bar per line of text

To draw bars where the lines are, I mask the element's background with a repeating gradient sized by the lh unit (one line-height):

mask-image: repeating-linear-gradient(
  to bottom,
  #000 0 calc(1lh - 0.3em),
  transparent calc(1lh - 0.3em) 1lh
);

Each line gets a bar, with a gap between lines. A paragraph that wraps to three lines gets three bars, at whatever width the browser chose.

Masking the whole element has a side effect: it also hides the element's own border, which matters for table cells. So the mask has two more layers, a border-box layer and a padding-box layer combined with mask-composite: exclude. Together they leave a ring where the border is, so table grid lines survive.

Images get object-position: -99999px, which slides the picture out of its own box while the box keeps its size and radius. Buttons and inputs become solid blocks.

Proving that nothing moves

"Nothing moves" is easy to claim and hard to test. jsdom, which most Vue tests run in, has no layout engine: every element is 0×0, so any position assertion passes.

So the visual rules are tested in a real Chromium with Vitest Browser Mode and Playwright. The main test records the bounding box of every element, turns the skeleton on, and records them again:

it("does not move or resize a single element", async () => {
  const before = rects();
  await skeletonize();
  expect(rects()).toEqual(before);
});

It runs in CI on every push, so any CSS change that shifts a single pixel fails the build.

The SSR bug I almost shipped

With server rendering and placeholder data, you want the skeleton in the server HTML, so fake content never flashes. Directives don't run on the server, but Vue has a getSSRProps hook for exactly this, and Vue 3.5's data-allow-mismatch lets hydration accept the attributes the client sets again.

The bug was in restoring attributes. When the skeleton ends, the directive puts back whatever inert and aria-hidden the element had before. My first version read "before" from the DOM. After SSR, the DOM already contained the skeleton's own inert, so it saved inert as the original value. When loading ended, it restored it, and the whole section stayed unclickable forever.

The fix was to read the original values from the vnode, which is what the template actually binds, never from the DOM. A test now server-renders, hydrates, ends the load and checks that no attribute is left behind.

Timing: when to show it at all

A skeleton that flashes for 80ms on a fast request feels worse than no skeleton. So v-skeleton waits 200ms before showing anything, and once shown it stays for at least 500ms so it never blinks off:

<!-- refreshing real data: keep the delay -->
<UserCard v-skeleton="refreshing" :user="user" />

<!-- first load with placeholder data: show it from the first frame -->
<ul v-skeleton="{ loading, delay: 0 }">…</ul>

The timing tests use fake timers and record the value at every 10ms step, so a single wrong frame fails them. Checking only the final state would miss a flash in the middle.

What 100% coverage missed

The package had about 99% line coverage, and I still didn't know whether the tests would notice a broken default. So I ran Stryker, which plants small bugs in the source (flips a condition, changes a constant, drops a call) and reruns the tests for each one.

The first score was 80%. Some of the surviving mutants were real gaps: you could change the table skeleton's default row height and no test failed. Two were real bugs:

v-skeleton removed an aria-hidden that the template had bound to false, while Vue itself renders it as "false".
The color helper accepted #12345z as a valid hex color, because parseInt("5z", 16) stops at the bad digit and returns 5.

After closing the gaps the score is above 90%. The rest are mostly equivalent mutants, changes no test could observe, which is why 100% isn't the goal.

Limits

It's CSS, so it has CSS's blind spots. The last line of a wrapped paragraph gets a full-width bar, because CSS can't know where the text ends. A few characters on a colored circle (an initials avatar) look like text, so you mark them data-skeleton="block". And it needs browsers from late 2023 on, for :has(), lh and mask-composite.

Try it

npm install vue-smart-loading-kit

import VueSmartLoadingKit from 'vue-smart-loading-kit'
import 'vue-smart-loading-kit/style.css'

app.use(VueSmartLoadingKit)

The kit also has a SmartLoader component with an error state and retry, 13 skeleton variants, 9 spinners and progress bars.

Live demo: https://navidjaberi.github.io/vue-smart-loading-kit/
GitHub: https://github.com/navidjaberi/vue-smart-loading-kit

I'd love feedback, especially on layouts where the skeleton doesn't look right.