@capgo/capacitor-native-loader

Native animated loaders for Capacitor apps. Render loaders above the WebView with platform-native SwiftUI, Android Canvas, Lottie, or image assets, while optionally resizing/insetting the WebView so native loading states can share space with web content.

• Native loader styles: siri, siri-v2, chrome, orbit, ring, pulse, dots, bars, wave, halo, and around.
• Asset loaders: native Lottie JSON and native image views from bundled assets, file URLs, remote URLs, or data URLs.
• Placements: center, top, bottom, left, right, fullscreen, around the screen, or custom frame.
• Transparent overlays with pass-through, blocking, or loader-only touch handling.
• WebView layout control: resize or inset the Capacitor WebView while a loader is visible, then restore it on hide.
• Public native API: call NativeLoader.shared from Swift or NativeLoader.show(...) from Kotlin/Java plugins without going through JavaScript.
• Reduced-motion aware native animations.

Loader	Demo	Loader	Demo
Siri		Siri v2
Chrome top		Ring
Dots		Bars
Wave		Orbit
Pulse		Halo
Around		Lottie
Image

Regenerate previews with:

bun run previews

The preview clips are captured from the example app running in a real simulator/emulator and sliced into WebP demos.

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-native-loader` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-native-loader
npx cap sync

import { NativeLoader } from '@capgo/capacitor-native-loader';

const { id } = await NativeLoader.show({
  style: 'siri',
  placement: 'fullscreen',
  message: 'Preparing update',
  colors: ['#71f6ff', '#8b5cf6', '#ff4ecd', '#fff7ad'],
  scrimColor: 'rgba(3, 7, 18, 0.42)',
  interactionMode: 'block',
  accessibilityLabel: 'Preparing update',
});

await NativeLoader.hide({ id });

const loader = await NativeLoader.show({
  style: 'bars',
  placement: 'bottom',
  message: 'Uploading',
  webView: {
    mode: 'resize',
    insets: { bottom: 96 },
    restoreOnHide: true,
  },
});

await NativeLoader.setProgress({ id: loader.id, progress: 0.72 });
await NativeLoader.hide({ id: loader.id });

const loader = await NativeLoader.show({
  style: 'chrome',
  placement: 'top',
  colors: ['#4285f4', '#34a853', '#fbbc05', '#ea4335'],
  thickness: 4,
  interactionMode: 'passThrough',
  webView: {
    mode: 'resize',
    insets: { top: 12 },
    restoreOnHide: true,
  },
});

await NativeLoader.hide({ id: loader.id, restoreWebView: true });

await NativeLoader.show({
  style: 'lottie',
  asset: {
    source: 'loader.json',
    type: 'lottie',
    loop: true,
    speed: 1,
  },
});

await NativeLoader.show({
  style: 'image',
  asset: {
    source: 'file:///var/mobile/Containers/Data/loader.webp',
    type: 'image',
  },
});

Swift:

import NativeLoaderPlugin

let id = NativeLoader.shared.show(options: [
    "style": "halo",
    "placement": "top",
    "message": "Syncing"
])

NativeLoader.shared.hide(id: id)

Kotlin:

import app.capgo.nativeloader.NativeLoader

val id = NativeLoader.show(activity, mapOf(
    "style" to "orbit",
    "placement" to "bottom",
    "message" to "Syncing"
))

NativeLoader.hide(id)

• iOS uses SwiftUI for built-in loaders and lottie-spm / lottie-ios for Lottie assets.
• Android uses custom Canvas views for built-in loaders and Airbnb Lottie for Lottie assets.
• Web has a CSS fallback for local demos and browser-based development.
• No permissions are required.

• Docs: https://capgo.app/docs/plugins/native-loader/
• Tutorial: https://capgo.app/plugins/capacitor-native-loader/
• Repository: https://github.com/Cap-go/capacitor-native-loader

• configure(...)
• show(...)
• update(...)
• setProgress(...)
• hide(...)
• hideAll(...)
• setWebViewLayout(...)
• resetWebViewLayout(...)
• getState()
• getPluginVersion()
• Interfaces
• Type Aliases

Native loader controller.

configure(options: NativeLoaderConfigureOptions) => Promise<void>

Configure defaults used by future show calls.

show(options?: NativeLoaderShowOptions | undefined) => Promise<NativeLoaderShowResult>

Show a native loader.

Returns: Promise<NativeLoaderShowResult>

update(options: NativeLoaderUpdateOptions) => Promise<void>

Update an existing native loader.

setProgress(options: NativeLoaderProgressOptions) => Promise<void>

Update determinate progress for a visible loader.

hide(options?: NativeLoaderHideOptions | undefined) => Promise<void>

Hide one loader.

hideAll(options?: NativeLoaderHideOptions | undefined) => Promise<void>

Hide every visible loader.

setWebViewLayout(options: NativeLoaderWebViewLayout) => Promise<void>

Apply a native WebView layout change without showing a loader.

resetWebViewLayout(options?: { animated?: boolean | undefined; } | undefined) => Promise<void>

Restore the WebView layout captured before setWebViewLayout or show.

getState() => Promise<NativeLoaderStateResult>

Read current loader state.

Returns: Promise<NativeLoaderStateResult>

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Global defaults applied to future show calls.

Loader display options.

Absolute frame in CSS pixels / device-independent points.

Native file, bundled asset, remote URL, or data URL used by lottie and image loaders.

Native WebView layout mutation.

Insets in CSS pixels / device-independent points.

Show result.

Update an existing loader. Any omitted property keeps its current value.

Progress update options.

Hide options.

Current loader state.

Plugin version payload.

Built-in native loader renderer.

• siri: blurred, rotating multi-orb loader inspired by assistant listening UI.
• siri-v2: full-screen Siri-style color motion around the screen edge.
• chrome: full-width top edge progress bar inspired by browser page loading UI.
• orbit: dots orbiting a transparent center.
• ring: rotating stroked ring.
• pulse: expanding translucent ripples.
• dots: three bouncing dots.
• bars: equalizer-style vertical bars.
• wave: flowing horizontal wave.
• halo: glowing radial halo.
• lottie: native Lottie JSON animation from asset.
• image: native image view from asset, rotating when autoPlay is enabled.

'siri' | 'siri-v2' | 'chrome' | 'orbit' | 'ring' | 'pulse' | 'dots' | 'bars' | 'wave' | 'halo' | 'lottie' | 'image'

Where the loader is anchored in the native window.

'center' | 'top' | 'bottom' | 'left' | 'right' | 'fullscreen' | 'around' | 'custom'

How the native overlay handles pointer/touch input while the loader is visible.

'passThrough' | 'block' | 'loaderOnly'

How platform reduced-motion settings affect animated loaders.

'system' | 'pause' | 'slow' | 'ignore'

Loader asset type.

'lottie' | 'image'

How to alter the Capacitor WebView while a loader is visible.

'none' | 'resize' | 'inset'