DEV Community: Navid jaberi

I ran my Vue skeleton directive on Vuetify and Nuxt UI, and five things broke

Navid jaberi — Wed, 04 Nov 2026 10:21:18 +0000

A while ago I wrote about v-skeleton, a directive that turns a real component into its own loading skeleton:

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

You don't build a second placeholder component. The directive restyles the markup you already have with CSS: text turns into bars, images and buttons turn into blocks, and the layout stays where it was. It never touches the DOM or any sizes, so nothing on the page jumps when loading ends.

I had only tested it on plain HTML fixtures I wrote myself. Most Vue apps render through a component library, though, so I put it on real Vuetify 4 and Nuxt UI 4 components (v-card, v-list, v-table, v-chip, UCard, UBadge, UTable, UAlert) and had a close look.

What broke

Here's the Vuetify page with real content:

And the same page with v-skeleton in 0.4.0:

At a glance it passes. Then I started counting the problems:

The icon-font icons were gone. mdi-account and the chevron in the list left empty gaps where they used to be.
v-table gives its rows a fixed height, so a one-word cell drew two or three bars stacked on top of each other.
The last line of the paragraph got a full-width bar. I knew about this one and had listed it in the README as a limitation.
The initials avatar turned into a striped circle.

Nuxt UI added a fifth:

The two badges at the top right merged into one long bar. <UBadge> renders a <span>, and the flex row around them is a <div> holding nothing but <span>s. My selector treats that as a line of text, so the whole row got one bar.

Why

Problems 2 to 5 come from the same place. I drew the bars like this:

/* paint the element's box, then cut it into one stripe per line */
background-color: var(--base);
mask-image: repeating-linear-gradient(
  to bottom,
  #000 0 calc(1lh - 0.3em),
  transparent calc(1lh - 0.3em) 1lh
);

That paints the element's whole box and slices it into stripes, one per line height. CSS has no idea where the text sits inside the box. A tall cell gets as many stripes as fit in its height. A flex row gets one stripe as wide as the row. The last line of a paragraph gets a stripe as wide as the paragraph. A small circle with two letters in it gets cut in half.

I needed something the browser draws per line of text, and only as wide as the text. CSS has that already: an underline.

The fix: a very thick underline, moved up over the text

text-decoration: underline solid;
text-decoration-color: var(--base);
text-decoration-thickness: 0.9em;
text-underline-offset: -0.75em; /* pull it up over the glyphs */
text-decoration-skip-ink: none; /* keep it solid under descenders */

The glyphs are already invisible (-webkit-text-fill-color: transparent), so you only see a solid bar behind each line. The browser does the line breaking, and each bar ends where that line's text ends.

Here's the Vuetify page with the new bars:

The paragraph's last line is short now, and each table cell has one bar as wide as its word. The avatar shows a short bar on its blue circle, which reads better than stripes. Since the bars no longer paint the element's box, the element keeps its own background and borders. That also let me delete a mask layer I had added only to keep table borders visible.

And Nuxt UI:

Each badge keeps its pill shape and gets its own bar.

The missing icons needed a separate fix. An icon font draws its glyph in ::before, and to CSS that glyph is text, so it disappeared along with the rest of the text. Selectors can't see what a pseudo-element contains, so I went with a heuristic: an empty <i>, or an empty element with icon in its class name, becomes a block the size of the icon. That catches Material Design Icons and Font Awesome, plus CSS icons such as Iconify's, which are empty <span>s masked to the icon's shape.

:is(i, [class*="icon"]):empty {
  background-color: var(--base);
}

Animating an underline

The old bars were backgrounds, so the shimmer was a gradient sliding across background-image. You can't put a gradient on a text decoration, so both animations needed another approach.

For shimmer, I slide a mask across the element instead. A soft band of lower opacity moves over the bars.

Pulse was harder. The rule uses !important so it can beat the page's own styles, and CSS animations can't override an !important declaration. So the bar color comes from a registered custom property, and the animation changes that property:

@property --bar-color {
  syntax: "<color>";
  inherits: false;
  initial-value: transparent;
}

.bar {
  --bar-color: var(--base);
  text-decoration-color: var(--bar-color) !important;
  animation: pulse 1.5s ease-in-out infinite;
}

@keyframes pulse {
  50% { --bar-color: var(--highlight); }
}

The animation targets --bar-color, so the !important on text-decoration-color doesn't get in its way.

A bug I caught in the screenshots

While making the "after" screenshots for this post, I noticed the text bars looked lighter than the buttons next to them. The default base color is translucent, and with shimmer each block paints the gradient on top of its base color, so blocks show the base twice. A text bar has one layer. I gave the text bars the base composited over itself, using relative color syntax:

rgb(from var(--base) r g b / calc(1 - (1 - alpha) * (1 - alpha)))

I shipped that as 0.5.1, the same day as 0.5.0. Looking at before and after side by side found a bug my tests had missed, and the fix came with a new test.

What still isn't perfect

An initials avatar gets a short bar on its colored circle. If you'd rather have a solid circle, add data-skeleton="block" to it.
Pulse on text bars needs @property, which Firefox only has from version 128. Older browsers show the bars without the pulse.
The icon check is a guess. An empty element that draws an icon in ::before without icon in its class name will still vanish. data-skeleton="block" fixes that one too.

Try it

StackBlitz example, runs in your browser with nothing to install
Live demo
GitHub
Nuxt: npx nuxi module add nuxt-smart-loading-kit

If you use PrimeVue, Quasar, Element Plus or another library, I'd like to hear where it looks wrong. Testing on real components is how I found these five.

My Vue Library Had 99% Line Coverage. Mutation Testing Found Two Bugs Anyway.

Navid jaberi — Sun, 25 Oct 2026 12:37:01 +0000

On October 2nd, vue-smart-loading-kit had 1,369 unit tests and 99% line coverage. That afternoon I added Stryker for mutation testing. About an hour and a half later I released 0.3.1 with fixes for two bugs my tests had missed.

What mutation testing checks

Coverage tells you which lines ran during your tests. It can't tell you whether a test would fail if one of those lines were wrong.

Stryker checks that part. It makes one small change to your source at a time, like flipping a condition, changing a default or removing a call, and runs your tests against each changed version. Each version is called a mutant. If a test fails, the mutant is killed. If all your tests still pass, it survived, and you've found code that no test really checks.

The config

I run mutation testing against the unit tests only. My real-browser tests are too slow to rerun for every mutant.

{
  "testRunner": "vitest",
  "vitest": { "configFile": "vitest.stryker.config.ts" },
  "mutate": ["src/**/*.{ts,vue}", "!src/**/*.d.ts", "!src/**/types.ts", "!src/**/*.types.ts"],
  "coverageAnalysis": "perTest",
  "ignoreStatic": true,
  "incremental": true,
  "plugins": ["@stryker-mutator/vitest-runner", "./scripts/stryker-vue-macros.mjs"],
  "ignorers": ["vue-macros"],
  "thresholds": { "high": 90, "low": 80, "break": null }
}

vitest.stryker.config.ts is my unit test config with tests/browser/** excluded. With incremental on, Stryker saves its results to a file, and the next run only retests mutants touched by changed code or tests. In CI I cache that file between runs, so a small commit doesn't mean a full run.

Workaround 1: Vitest 5 skips every test

With @stryker-mutator/vitest-runner 10.0.0 and Vitest 5, every mutant survives. The report makes your tests look useless, and none of them actually ran.

For each mutant, the runner picks the tests to run with a name pattern. It builds that pattern by joining suite and test names with a space. Vitest 5 joins them with " > ", so the pattern matches nothing and Vitest skips everything.

I run this script before each mutation run. It patches the join in the runner's two files:

// scripts/stryker-vitest5-fix.mjs
import { readFileSync, writeFileSync } from 'node:fs'

const dir = 'node_modules/@stryker-mutator/vitest-runner/dist/src'
const before = "return nameParts.join(' ').trim();"
const after = "return nameParts.filter(Boolean).join(' > ').trim();"

for (const file of ['test-helpers.js', 'stryker-setup.js']) {
  const path = `${dir}/${file}`
  const source = readFileSync(path, 'utf8')
  if (source.includes(after)) continue
  if (!source.includes(before)) {
    throw new Error(`${path}: collectTestName changed; check whether this workaround is still needed`)
  }
  writeFileSync(path, source.replace(before, after))
}

If the runner's code changes, the script throws, so I'll find out when I can delete it. That was the state of things in early October. Check your runner version before you copy this.

Workaround 2: Vue's compiler macros

When Vue compiles a <script setup> component, it moves the arguments of defineProps, withDefaults and the other macros out of setup(). A mutant in there calls Stryker's helper functions before they exist, and the component fails to compile.

An ignorer plugin tells Stryker to leave those calls alone:

// scripts/stryker-vue-macros.mjs
import { PluginKind, declareValuePlugin } from '@stryker-mutator/api/plugin'

const MACROS = new Set(['defineProps', 'withDefaults', 'defineEmits', 'defineModel', 'defineSlots', 'defineOptions'])

export const strykerPlugins = [
  declareValuePlugin(PluginKind.Ignore, 'vue-macros', {
    shouldIgnore(path) {
      if (path.isCallExpression() && MACROS.has(path.node.callee.name)) {
        return 'Vue compiler macro: arguments are hoisted out of setup()'
      }
    },
  }),
]

The prop defaults still have tests. The component tests cover them.

Bug 1: `#12345z` parsed as a color

The skeleton works out its highlight color from your base color, so the library has a small color parser. Here's the old hex part, shortened:

function parseHex(hex: string): RGBA | null {
  const h = hex.replace('#', '').trim()
  if (![3, 4, 6, 8].includes(h.length)) return null
  // ...
  r = parseInt(h.slice(0, 2), 16)
  g = parseInt(h.slice(2, 4), 16)
  b = parseInt(h.slice(4, 6), 16)
  // ...
  if ([r, g, b, a].some((n) => Number.isNaN(n))) return null
  return { r, g, b, a: a / 255 }
}

parseInt reads digits until it hits a character it can't use, then returns what it has so far:

parseInt('zz', 16) // NaN
parseInt('5z', 16) // 5

So the NaN check rejected #zz1234 and let #12345z through as { r: 18, g: 52, b: 5, a: 1 }. In a six- or eight-digit color, it only caught a bad character when it came first in its pair.

In fairness to coverage, the warning was there if I had looked per file. color.ts was one of my weakest files at 75% of statements, and the return null lines for bad input had never run. I was looking at the 99% total.

The fix checks the whole string up front:

if (![3, 4, 6, 8].includes(h.length) || !/^[0-9a-f]+$/i.test(h)) return null

After that, parseInt can't return NaN here, so I deleted the old check. A mutant inside a condition that can never be true has no test that could kill it.

Bug 2: `aria-hidden="false"` disappeared after loading

This one was in a file with 100% line coverage.

While v-skeleton is showing, it sets inert, aria-hidden and aria-busy on your element. When loading ends, it puts back what your template bound. The old code treated false as "remove the attribute":

if (v === undefined || v === null || v === false) return [name, null]
if (v === true) return [name, name === 'inert' ? '' : 'true']
return [name, String(v)]

Vue 3 doesn't remove an aria-* attribute bound to false. It renders the string "false":

<section v-skeleton="loading" :aria-hidden="false">
  ...
</section>

Before loading, that element had aria-hidden="false". After loading, the attribute was gone. The line with v === false ran in my tests, but no test bound an aria attribute to false and checked what came back.

The fix copies Vue's behavior. inert is the exception, because Vue sets it as a DOM property instead of an attribute:

if (v === undefined || v === null) return [name, null]
if (name === 'inert' && typeof v === 'boolean') return [name, v ? '' : null]
return [name, String(v)]

If you run the tests from that fix against the old code, both fail with exactly these values: the parser returns { r: 18, g: 52, b: 5, a: 1 } for #12345z, and aria-hidden comes back as null instead of "false".

After the fixes

The mutation score is over 90%. It's a live badge in the README, and the full report is published with the demo, so you can see which mutants still survive. I also raised the coverage thresholds in CI the same day, to 98% of statements and 99% of lines.

The score doesn't fail the build (break: null). Some mutants don't change what the code does at all, and no test can kill those.

For a library this size, the setup was one config file and two short scripts, and it found real bugs on the first afternoon.

If you try it

Read the list of surviving mutants before you look at the score. For me, the survivors pointed at files that the total coverage number made look fine.

npm: vue-smart-loading-kit
GitHub: https://github.com/navidjaberi/vue-smart-loading-kit
Mutation report: https://navidjaberi.github.io/vue-smart-loading-kit/mutation/
More about v-skeleton: I built a Vue directive that turns your real component into its own skeleton
I also write about Vue and frontend on LinkedIn

If you've tried mutation testing on a Vue or React project, what did the survivors show you?

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.

DEV Community: Navid jaberi

I ran my Vue skeleton directive on Vuetify and Nuxt UI, and five things broke

What broke

Why

The fix: a very thick underline, moved up over the text

Animating an underline

A bug I caught in the screenshots

What still isn't perfect

Try it

My Vue Library Had 99% Line Coverage. Mutation Testing Found Two Bugs Anyway.

What mutation testing checks

The config

Workaround 1: Vitest 5 skips every test

Workaround 2: Vue's compiler macros

Bug 1: #12345z parsed as a color

Bug 2: aria-hidden="false" disappeared after loading

After the fixes

If you try it

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

The naive version

Adding a delay creates a new problem

Two numbers

A simplified version of the idea

Timing is only half of it

Trade-offs, and what else is out there

Takeaway

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

The rule: never change the DOM

Hiding text without breaking borders

One bar per line of text

Proving that nothing moves

The SSR bug I almost shipped

Timing: when to show it at all

What 100% coverage missed

Limits

Try it

Bug 1: `#12345z` parsed as a color

Bug 2: `aria-hidden="false"` disappeared after loading