API reference

Components

VLoader

The generic loader. The variant prop selects one of the 36 treatments and every named loader is a thin wrapper around it.

VLoader props
Prop	Type	Default	Description
`variant`	`"bars" \| "bounce" \| "dots" \| "dot-sweep" \| "equalizer" \| "sliding-bars" \| "spin" \| "spin-dots" \| "typing" \| "wave" \| "breathing" \| "dual-arc" \| "gradient-ring" \| "orbit" \| "orbit-dots" \| "progress-ring" \| "pulse" \| "ring" \| "ripple" \| "rotate" \| "signal" \| "snake" \| "blob" \| "card-flip" \| "element" \| "flow" \| "grid" \| "hashtag" \| "heatmap" \| "liquid" \| "logo-spin" \| "morph" \| "plane" \| "squares" \| "stair" \| "fallback"`	`"spin"`	Selects the treatment rendered by the component. Unknown values fall back to `spin`.
`color`	`string`	`"currentColor"`	Primary colour of the loader. Accepts any CSS colour value, including `currentColor`.
`size`	`number`	`40`	Diameter or height of the loader in pixels. Values below 12 are clamped to 12.
`duration`	`number`	`1000`	Duration of one animation cycle in milliseconds. Values below 100 are clamped to 100.
`count`	`number`	`4 (9 for heatmap/squares; 2 fixed for breathing/dual-arc)`	Number of marks rendered by treatments that repeat an element. Clamped to 1–12.
`label`	`string`	`"Loading"`	Accessible name announced by the status region. An empty label makes the loader decorative.
`decorative`	`boolean`	`false`	Hides the loader from assistive technology. Use it when an ancestor already announces the loading state.
`value`	`number \| null`	`null`	Completion percentage between 0 and 100. Only the progress ring renders the value.

VSkeleton

The skeleton primitive. It is also exported as VSkeletonLoader for catalogue parity.

VSkeleton props
Prop	Type	Default	Description
`variant`	`"text" \| "rect" \| "circle"`	`"text"`	Shape of the placeholder. Unknown values fall back to `text`.
`width`	`number \| string`	`—`	Width as a pixel number or any CSS length. Defaults to `100%`, or `40px` for circles.
`height`	`number \| string`	`—`	Height as a pixel number or any CSS length. Defaults to `1em` for text and `6rem` for rectangles.
`borderRadius`	`number \| string`	`—`	Border radius as a pixel number or any CSS length. A shape appropriate default is used when omitted.
`animated`	`boolean`	`true`	Enables the shimmer animation. Reduced-motion preferences always disable it.
`label`	`string`	`—`	Accessible name announced by the status region. Without a label the skeleton is decorative.

VPatternSkeleton

Renders one of the eleven layout patterns from a single component.

VPatternSkeleton props
Prop	Type	Default	Description
`pattern`	`"lines" \| "article" \| "card" \| "profile" \| "list" \| "table" \| "media" \| "form" \| "dashboard" \| "feed" \| "product"`	`"lines"`	Layout pattern rendered by the component.
`rows`	`number`	`3`	Number of repeated text lines, list items, fields or data rows. Clamped to 1–12. Table and dashboard headers are separate; dashboard always includes one fixed header.
`columns`	`number`	`3`	Number of columns in table and dashboard layouts. Clamped to 1–6.
`mediaHeight`	`number \| string`	`—`	Height of the media block in pixels or any CSS length.
`avatarSize`	`number`	`48`	Diameter of the avatar block in pixels. Clamped to 1–160.
`color`	`string`	`—`	Base colour of the placeholder blocks. Falls back to `--v-skeleton-base-color`.
`highlightColor`	`string`	`—`	Colour of the shimmer highlight. Falls back to `--v-skeleton-highlight-color`.
`animated`	`boolean`	`true`	Enables the shimmer animation. Reduced-motion preferences always disable it.
`label`	`string`	`—`	Accessible name announced by the status region. Without a label the skeleton stays hidden from assistive technology.
`showMedia`	`boolean`	`true`	Toggles the media block where the pattern supports one.
`showAvatar`	`boolean`	`true`	Toggles the avatar block where the pattern supports one.
`showHeader`	`boolean`	`true`	Toggles the table header row.
`showChart`	`boolean`	`true`	Toggles the dashboard chart block.
`showStats`	`boolean`	`true`	Toggles the statistic tiles used by profile and dashboard patterns.
`showSubmit`	`boolean`	`true`	Toggles the submit block used by the form pattern.
`showRating`	`boolean`	`true`	Toggles the rating block used by the product pattern.
`showPrice`	`boolean`	`true`	Toggles the price block used by the product pattern.
`showCta`	`boolean`	`true`	Toggles the call-to-action block used by the product pattern.

VSkeletonGroup

Groups placeholders with a shared gap and exposes the group as one status region.

VSkeletonGroup props
Prop	Type	Default	Description
`label`	`string`	`—`	Accessible name announced by the group. Without a label the group does not create a status region.
`gap`	`string`	`"0.75rem"`	CSS gap between the child placeholders.
`decorative`	`boolean`	`false`	Hides the whole group from assistive technology.

VSkeletonSwitch

Shows a skeleton while loading and the default slot afterwards.

VSkeletonSwitch props
Prop	Type	Default	Description
`loading`	`boolean`	`true`	Renders the skeleton while `true` and the default slot afterwards.
`pattern`	`"lines" \| "article" \| "card" \| "profile" \| "list" \| "table" \| "media" \| "form" \| "dashboard" \| "feed" \| "product"`	`"lines"`	Layout pattern rendered by the component.
`rows`	`number`	`3`	Number of repeated text lines, list items, fields or data rows. Clamped to 1–12. Table and dashboard headers are separate; dashboard always includes one fixed header.
`columns`	`number`	`—`	Number of columns in table and dashboard layouts. Clamped to 1–6.
`mediaHeight`	`number \| string`	`—`	Height of the media block in pixels or any CSS length.
`avatarSize`	`number`	`48`	Diameter of the avatar block in pixels. Clamped to 1–160.
`color`	`string`	`—`	Base colour of the placeholder blocks. Falls back to `--v-skeleton-base-color`.
`highlightColor`	`string`	`—`	Colour of the shimmer highlight. Falls back to `--v-skeleton-highlight-color`.
`animated`	`boolean`	`true`	Enables the shimmer animation. Reduced-motion preferences always disable it.
`label`	`string`	`"Loading content"`	Accessible name announced by the status region. Without a label the skeleton stays hidden from assistive technology.
`showMedia`	`boolean`	`true`	Toggles the media block where the pattern supports one.
`showAvatar`	`boolean`	`true`	Toggles the avatar block where the pattern supports one.
`showHeader`	`boolean`	`true`	Toggles the table header row.
`showChart`	`boolean`	`true`	Toggles the dashboard chart block.
`showStats`	`boolean`	`true`	Toggles the statistic tiles used by profile and dashboard patterns.
`showSubmit`	`boolean`	`true`	Toggles the submit block used by the form pattern.
`showRating`	`boolean`	`true`	Toggles the rating block used by the product pattern.
`showPrice`	`boolean`	`true`	Toggles the price block used by the product pattern.
`showCta`	`boolean`	`true`	Toggles the call-to-action block used by the product pattern.

VSkeletonSwitch slots
Slot	Description
`default`	The loaded content.
`skeleton`	Custom placeholder shown while `loading` is `true`. Defaults to the selected pattern.

VAutoSkeleton

A safe content switcher. It never inspects slot content to infer a layout, it renders the pattern you choose.

VAutoSkeleton props
Prop	Type	Default	Description
`loading`	`boolean`	`true`	Renders the skeleton while `true` and the default slot afterwards.
`pattern`	`"lines" \| "article" \| "card" \| "profile" \| "list" \| "table" \| "media" \| "form" \| "dashboard" \| "feed" \| "product"`	`"lines"`	Layout pattern rendered by the component.
`rows`	`number`	`3`	Number of repeated text lines, list items, fields or data rows. Clamped to 1–12. Table and dashboard headers are separate; dashboard always includes one fixed header.
`columns`	`number`	`—`	Number of columns in table and dashboard layouts. Clamped to 1–6.
`mediaHeight`	`number \| string`	`—`	Height of the media block in pixels or any CSS length.
`avatarSize`	`number`	`48`	Diameter of the avatar block in pixels. Clamped to 1–160.
`color`	`string`	`—`	Base colour of the placeholder blocks. Falls back to `--v-skeleton-base-color`.
`highlightColor`	`string`	`—`	Colour of the shimmer highlight. Falls back to `--v-skeleton-highlight-color`.
`animated`	`boolean`	`true`	Enables the shimmer animation. Reduced-motion preferences always disable it.
`label`	`string`	`"Loading content"`	Accessible name announced by the status region. Without a label the skeleton stays hidden from assistive technology.
`showMedia`	`boolean`	`true`	Toggles the media block where the pattern supports one.
`showAvatar`	`boolean`	`true`	Toggles the avatar block where the pattern supports one.
`showHeader`	`boolean`	`true`	Toggles the table header row.
`showChart`	`boolean`	`true`	Toggles the dashboard chart block.
`showStats`	`boolean`	`true`	Toggles the statistic tiles used by profile and dashboard patterns.
`showSubmit`	`boolean`	`true`	Toggles the submit block used by the form pattern.
`showRating`	`boolean`	`true`	Toggles the rating block used by the product pattern.
`showPrice`	`boolean`	`true`	Toggles the price block used by the product pattern.
`showCta`	`boolean`	`true`	Toggles the call-to-action block used by the product pattern.

VAutoSkeleton slots
Slot	Description
`default`	The loaded content.
`skeleton`	Custom placeholder shown while `loading` is `true`. Defaults to the selected pattern.

VSpinner

A compact status spinner for inline work.

VSpinner props
Prop	Type	Default	Description
`size`	`number`	`24`	Diameter of the spinner in pixels. Negative and non-finite values are normalised.
`color`	`string`	`"currentColor"`	Accent colour of the active edge. The track uses `--v-spinner-track-color`.
`label`	`string`	`"Loading"`	Accessible name announced by the status region. An empty label makes the spinner decorative.
`decorative`	`boolean`	`false`	Hides the spinner from assistive technology. Use it when an ancestor already announces the loading state.

VProgress

A determinate or indeterminate progress bar.

VProgress props
Prop	Type	Default	Description
`value`	`number \| null`	`null`	Current value. Omit it, pass `null`, or pass a non-finite value for an indeterminate bar.
`min`	`number`	`0`	Lower bound of the value range.
`max`	`number`	`100`	Upper bound of the value range. When `max` is not greater than `min` the bar is indeterminate.
`label`	`string`	`"Progress"`	Accessible name of the progress bar.
`valueText`	`string`	`—`	Human readable value exposed through `aria-valuetext`. Only used while determinate.
`height`	`number \| string`	`8`	Thickness of the bar in pixels or any CSS length.
`color`	`string`	`—`	Colour of the filled portion. Overrides `--v-progress-color`.
`trackColor`	`string`	`—`	Colour of the unfilled track. Overrides `--v-progress-track-color`.

VLoading

Wraps content in an overlay and makes that content inert while it loads.

VLoading props
Prop	Type	Default	Description
`loading`	`boolean`	`false`	Shows the overlay, sets `aria-busy` on the wrapper and makes the content inert.
`label`	`string`	`"Loading"`	Loading message. It is visually hidden and announced by the status region.
`inertContent`	`boolean`	`true`	Makes the wrapped content inert while the overlay is active.
`indicatorSize`	`number`	`28`	Diameter of the built-in spinner in pixels.

VLoading slots
Slot	Description
`default`	The content being loaded.
`indicator`	Replaces the built-in spinner.

VLoadingButton

A native button with a loading state.

VLoadingButton props
Prop	Type	Default	Description
`loading`	`boolean`	`false`	Disables the button, sets `aria-busy` and shows the indicator.
`disabled`	`boolean`	`false`	Native disabled state. The button is also disabled while loading.
`type`	`"button" \| "submit" \| "reset"`	`"button"`	Native button type. The safe default avoids accidental form submission.
`indicatorSize`	`number`	`16`	Diameter of the default indicator in pixels.

VLoadingButton slots
Slot	Description
`default`	Button label. It stays in the accessibility tree and keeps its space while loading.
`indicator`	Replaces the built-in spinner.

Named loaders

Every named loader accepts the shared loader props: color, size, duration, count, label and decorative. VProgressRingLoader additionally accepts value.

Composables

useLoading()

Tracks concurrent asynchronous operations for a single loading state.

useLoading() members
Member	Type	Description
`isLoading`	`Readonly<Ref<boolean>>`	True while at least one operation is pending.
`pendingCount`	`Readonly<Ref<number>>`	Number of pending operations for this instance.
`execute`	`<T>(operation: () => Promise<T>) => Promise<T>`	Runs and tracks the operation. Results and errors pass through unchanged.

useDelayedLoading(options?)

Delays the indicator until the work has been pending for a while, so fast operations never flash a spinner.

useDelayedLoading(options?) members
Member	Type	Description
`delay`	`number`	Milliseconds to wait before isLoading becomes true. Defaults to 200.
`minVisibleDuration`	`number`	Minimum milliseconds the indicator stays visible once it appears. Defaults to 0.

useLoadingGroup(sources)

Aggregates independent loading sources into one state without owning them.

useLoadingGroup(sources) members
Member	Type	Description
`isLoading`	`ComputedRef<boolean>`	True when at least one source is active.
`activeCount`	`ComputedRef<number>`	Number of sources that are currently active.

Exported types

All prop and return types are exported from the package root.

Types

import {
  VLoader,
  type LoaderVariant,
  type NamedLoaderProps,
  type VProgressRingLoaderProps,
} from "veload";

CSS custom properties

Components use scoped styles and these custom properties. Set them on a component or on any ancestor.

CSS custom properties
Component	Custom property	Default
VSpinner	`--v-spinner-border-width`	`3px`
VSpinner	`--v-spinner-track-color`	`currentColor`
VSkeleton	`--v-skeleton-base-color`	`rgba(148, 163, 184, 0.28)`
VSkeleton	`--v-skeleton-highlight-color`	`rgba(255, 255, 255, 0.55)`
VSkeleton	`--v-skeleton-radius`	`0.25em (text), 0.5rem (rect)`
VSkeleton	`--v-skeleton-duration`	`1.4s`
VProgress	`--v-progress-color`	`#2563eb`
VProgress	`--v-progress-track-color`	`#e2e8f0`
VProgress	`--v-progress-radius`	`999px`
VProgress	`--v-progress-duration`	`1.4s`
VLoading	`--v-loading-overlay-background`	`rgba(255, 255, 255, 0.72)`
VLoading	`--v-loading-color`	`#334155`
VLoading	`--v-loading-z-index`	`10`
VLoading	`--v-loading-radius`	`inherit`
VLoading	`--v-loading-backdrop-filter`	`none`
VLoadingButton	`--v-loading-button-gap`	`0.5rem`

The loaders are styled entirely through their props, so they expose no custom properties.

VLoading uses a light translucent overlay by default, which assumes a light surface. On a dark surface, override --v-loading-overlay-background and --v-loading-color.