@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

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.. | v8.. | Yes | | v7.. | v7.. | On demand | | v6.. | v6.. | On demand |

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(...)
• show(...)
• update(...)
• setProgress(...)
• hide(...)
• hideAll(...)
• setWebViewLayout(...)
• resetWebViewLayout(...)
• getState()
• getPluginVersion()
• Interfaces
• Type Aliases

Native loader controller.

configure(...)

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

Configure defaults used by future show calls.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------- | | options | NativeLoaderConfigureOptions |

show(...)

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

Show a native loader.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | NativeLoaderShowOptions |

Returns: Promise<NativeLoaderShowResult>

update(...)

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

Update an existing native loader.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | NativeLoaderUpdateOptions |

setProgress(...)

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

Update determinate progress for a visible loader.

| Param | Type | | ------------- | ----------------------------------------------------------------------------------- | | options | NativeLoaderProgressOptions |

hide(...)

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

Hide one loader.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | NativeLoaderHideOptions |

hideAll(...)

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

Hide every visible loader.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | NativeLoaderHideOptions |

setWebViewLayout(...)

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

Apply a native WebView layout change without showing a loader.

| Param | Type | | ------------- | ------------------------------------------------------------------------------- | | options | NativeLoaderWebViewLayout |

resetWebViewLayout(...)

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

Restore the WebView layout captured before setWebViewLayout or show.

| Param | Type | | ------------- | ------------------------------------ | | options | { animated?: boolean; } |

getState()

getState() => Promise<NativeLoaderStateResult>

Read current loader state.

Returns: Promise<NativeLoaderStateResult>

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

Interfaces

NativeLoaderConfigureOptions

Global defaults applied to future show calls.

| Prop | Type | Description | | -------------- | --------------------------------------------------------------------------- | --------------------- | | defaults | NativeLoaderShowOptions | Default show options. |

NativeLoaderShowOptions

Loader display options.

| Prop | Type | Description | | ------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | id | string | Stable loader id. A generated id is returned when omitted. | | style | NativeLoaderStyle | Built-in style or asset renderer. Defaults to siri. | | placement | NativeLoaderPlacement | Native window placement. Defaults to center. | | frame | NativeLoaderFrame | Custom frame used when placement is custom. | | message | string | Optional loading message shown below or near the loader. | | size | number | Loader size in points / CSS pixels. Defaults to 96. | | thickness | number | Thickness for ring, edge, and progress loaders. Defaults to 5. | | duration | number | Animation duration in milliseconds for one cycle. Defaults vary by style. | | speed | number | Animation speed multiplier. Defaults to 1. | | progress | number | Determinate progress from 0 to 1. Omit for indeterminate loaders. | | colors | string[] | Loader colors. Built-in loaders use the first colors as gradient stops. | | backgroundColor | string | Container background color. | | scrimColor | string | Fullscreen scrim color. Used by fullscreen and around placements when set. | | cornerRadius | number | Corner radius for the floating container. Defaults to 24. | | blurRadius | number | Native blur radius where supported. Defaults to 0. | | autoHide | number | Hide automatically after this many milliseconds. | | interactionMode | NativeLoaderInteractionMode | Touch handling for the overlay. Defaults to passThrough unless scrimColor is set. | | reducedMotion | NativeLoaderReducedMotionMode | Reduced motion behavior. Defaults to system. | | accessibilityLabel | string | Accessibility label announced when the loader appears. | | asset | NativeLoaderAsset | Asset configuration for lottie and image loaders. | | webView | NativeLoaderWebViewLayout | Optional native WebView layout mutation while the loader is visible. |

NativeLoaderFrame

Absolute frame in CSS pixels / device-independent points.

| Prop | Type | Description | | ------------ | ------------------- | ------------- | | x | number | Left offset. | | y | number | Top offset. | | width | number | Frame width. | | height | number | Frame height. |

NativeLoaderAsset

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

| Prop | Type | Description | | -------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | source | string | Asset path or URL. Supported forms: - app bundle asset name, for example loader.json - file:// URL - https:// or http:// URL - data:application/json;base64,... for Lottie JSON - data:image/...;base64,... for images | | type | NativeLoaderAssetType | Explicit asset type. Defaults to the current loader style. | | loop | boolean | Repeat asset animation. Defaults to true. Lottie assets loop their composition. Image assets loop their native rotation. | | speed | number | Asset animation speed multiplier. Defaults to 1. Applies to Lottie playback speed and image rotation speed. | | autoPlay | boolean | Start asset animation immediately. Defaults to true. For image assets, this starts the native rotation loader. |

NativeLoaderWebViewLayout

Native WebView layout mutation.

| Prop | Type | Description | | ------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mode | NativeLoaderWebViewMode | Layout mode. resize changes the native WebView frame/margins. inset changes scroll content inset/padding where the platform supports it. none leaves the WebView untouched. | | insets | NativeLoaderInsets | Insets applied in resize or inset mode. | | frame | NativeLoaderFrame | Replace the WebView frame instead of using insets. Used only by iOS and by Android parents that support absolute layout params. | | restoreOnHide | boolean | Restore the previous WebView layout when the loader is hidden. Defaults to true. | | animated | boolean | Animate the layout change where the platform supports it. Defaults to true. |

NativeLoaderInsets

Insets in CSS pixels / device-independent points.

| Prop | Type | Description | | ------------ | ------------------- | ------------- | | top | number | Top inset. | | right | number | Right inset. | | bottom | number | Bottom inset. | | left | number | Left inset. |

NativeLoaderShowResult

Show result.

| Prop | Type | Description | | -------- | ------------------- | ------------------------------------------------------------------- | | id | string | Loader id that can be passed to update, setProgress, or hide. |

NativeLoaderUpdateOptions

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

| Prop | Type | Description | | -------- | ------------------- | -------------------- | | id | string | Loader id to update. |

NativeLoaderProgressOptions

Progress update options.

| Prop | Type | Description | | -------------- | ------------------- | ----------------------------------------------------------------------- | | id | string | Loader id. When omitted, the top-most/current loader receives progress. | | progress | number | Determinate progress from 0 to 1. |

NativeLoaderHideOptions

Hide options.

| Prop | Type | Description | | -------------------- | -------------------- | --------------------------------------------------------------- | | id | string | Loader id. When omitted, the top-most/current loader is hidden. | | animated | boolean | Animate dismissal. Defaults to true. | | restoreWebView | boolean | Restore WebView layout immediately. Defaults to true. |

NativeLoaderStateResult

Current loader state.

| Prop | Type | Description | | ------------- | --------------------- | ----------------------------------------- | | showing | boolean | Whether at least one loader is visible. | | ids | string[] | Visible loader ids from oldest to newest. |

PluginVersionResult

Plugin version payload.

| Prop | Type | Description | | ------------- | ------------------- | ----------------------------------------------------------- | | version | string | Version identifier returned by the platform implementation. |

Type Aliases

NativeLoaderStyle

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'

NativeLoaderPlacement

Where the loader is anchored in the native window.

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

NativeLoaderInteractionMode

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

'passThrough' | 'block' | 'loaderOnly'

NativeLoaderReducedMotionMode

How platform reduced-motion settings affect animated loaders.

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

NativeLoaderAssetType

Loader asset type.

'lottie' | 'image'

NativeLoaderWebViewMode

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

'none' | 'resize' | 'inset'