@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.

Features

• 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.

Preview

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.

Install

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

Usage

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 });

WebView Resize

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 });

Chrome-Style Top Progress

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 });

Lottie And Image Assets

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',
  },
});

Native Calls

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)

Compatibility

Platform Notes

• 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.

Links

• 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

API

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

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

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

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

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

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

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

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

getState() => Promise<NativeLoaderStateResult>

getPluginVersion() => Promise<PluginVersionResult>