Loading

Service and directive entry for displaying loading masks. It is built on top of YhSpin and is primarily used through YhLoading.service(...) and the v-yh-loading directive.

Relationship between Loading and Spin

Loading is the directive and service layer built on top of Spin, while Spin is the lower-level visual loading component.

• Spin is responsible for rendering icons, tips, and loading animation layouts.
• Loading adds service mounting, fullscreen masking, scroll locking, directive support, and temporary host management.

Usage

Regional Loading (Directive Version)

Use the v-yh-loading directive to cover a host element with a loading mask.

This is container content

Basic Usage

Advanced Directive Usage

Directive modifiers such as .fullscreen, .lock, and .glass, together with the yh-loading-* attributes, provide richer loading interactions.

Directive Fullscreen and Locking

This is a dark container background

Directive Extension Attributes

System Core Dashboard

Rendering real-time data stream through acrylic glass filter...

Directive Flagship Glass Mode

Asset Management Queue

Dot loading mode for lightweight container feedback

Directive Dot Mode

Deep Customization

Applying special filter via my-custom-mask class...

Directive Custom Class Name

Composition API (Recommended)

Use YhLoading.service inside setup to open and close loading masks imperatively.

Composition API Call

Options API

After installing the plugin, the service is also available through $loading.

Options API Call

Use in Nuxt

YhLoading works in Nuxt 3/4 after registering @yh-ui/nuxt. Call the service from client-side interaction handlers or lifecycle hooks, and use the directive directly in templates for container masks.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@yh-ui/nuxt']
})

Usage in Axios

In real projects, combine Axios interceptors with a small reference counter so the mask only closes after the last concurrent request finishes.

This counter strategy ensures that only the first request opens Loading, and the mask stays visible until the last concurrent request completes.

Network Request Interception Example

Flagship Loading Styles

Inspired by the motion styles of loading.io.

Premium Animations

Custom Color Schemes

Single colors, gradient color arrays, and CSS-variable based colors are all supported.

Multi-color Animations

Fully Custom Expansion (VNode or Component)

Pass a custom spinner to replace the built-in loading renderer with your own VNode or component.

Custom VNode Demo

Application Context

YhLoading.service accepts the current app context as the second argument so content rendered inside the service can inherit global components and plugins.

TIP

If YhLoading is installed globally, the service already runs with the application context created by the plugin.

By passing `appContext`, components mounted inside Loading can access globally registered plugins such as Pinia or Vue Router.

Application Context Injection

API

Props

This entry does not expose configuration through component props. Use YhLoading.service(...) or v-yh-loading instead.

Events

This entry does not expose component events.

Slots

This entry is not used as a regular template component and does not expose standalone component slots.

Expose

This entry does not expose component-instance defineExpose members. Service capabilities are returned from YhLoading.service(...).

Loading Options

Property	Description	Type	Default
target	Mount target element or selector	string | HTMLElement	document.body
body	Whether to append to the body container	boolean	false
fullscreen	Whether to render as a fullscreen fixed mask	boolean	true
lock	Whether to lock scrolling on the target	boolean	false
text	Loading tip text	string	undefined
spinner	Custom icon, component, or VNode	string | Component | VNode	undefined
background	Custom mask background color	string	undefined
customClass	Extra class name applied to the mask	string	undefined
glass	Whether to enable the glass-style mask	boolean	false
color	Spinner color, gradient colors, or color token map	string | string[] | Record<string, string>	undefined
dot	Whether to use the dot loading style	boolean	false
spinnerType	Built-in loading animation type	LoadingSpinnerType	'circle'
themeOverrides	Component-level theme variable overrides	ComponentThemeVars	undefined

Directive Attributes

Name	Description	Type
yh-loading-text	Loading tip text	string
yh-loading-background	Mask background color	string
yh-loading-custom-class	Extra custom class name	string
yh-loading-glass	Whether to enable glass mode	boolean
yh-loading-dot	Whether to enable dot mode	boolean
yh-loading-color	Spinner color	string
yh-loading-type	Built-in spinner type	LoadingSpinnerType

Directive Modifiers

Name	Description
.fullscreen	Equivalent to fullscreen: true
.lock	Equivalent to lock: true
.glass	Equivalent to glass: true

Loading Instance

Property	Description	Type
close	Close and destroy the mask	() => void
visible	Current visible state (readonly)	boolean

Theme Variables

Variable	Description	Default
--yh-loading-z-index	Loading mask z-index	2000

Type Exports

Name	Description
YhLoadingOptions	Service options type for YhLoading.service(...)
YhLoadingInstance	Returned loading instance type
vYhLoading	Named directive export for v-yh-loading