@capgo/capacitor-native-loader

Native render path

Show loaders as UIKit and Android overlay views instead of asking the WebView to animate expensive translucent effects.

Flexible placement

Place loaders fullscreen, centered, pinned to an edge, Chrome-style at the top, or around the WebView with safe-area-aware insets.

Built-in and asset loaders

Use native Siri-style, Chrome top progress, orbit, ring, pulse, dots, bars, wave, halo, image, or Lottie-based loaders.

Callable everywhere

Trigger loaders from JavaScript, Swift, Kotlin, or other native plugins through the public native API.

When To Use It

@capgo/capacitor-native-loader is for loading states that should stay smooth, translucent, and native while the WebView is busy, resizing, navigating, or hidden behind native surfaces.

Use it when you need:

• transparent full-screen loading layers above web content
• Chrome-style top progress bars that can resize the WebView instead of covering content
• edge loaders at the top, bottom, left, or right of the app
• loaders around a resized WebView while native content owns part of the screen
• native fallback loaders that survive heavy web rendering, route changes, or startup work
• shared loaders triggered by another native plugin before JavaScript is ready
• Lottie, bundled image, or remote asset-backed loading animations

Note

For web-only route animations, use @capgo/capacitor-transitions. Use Native Loader when the loading state itself should be native or when the WebView needs to be resized while loading.

Demo Styles

Style	Preview
Siri
Chrome top
Ring
Dots
Bars
Wave
Orbit
Pulse
Halo
Around
Lottie
Image

Core API

• show(options) displays a loader and returns its id.
• update(options) changes an existing loader without tearing down the overlay.
• setProgress(options) updates determinate loader progress.
• hide(options) removes one loader.
• hideAll(options) removes all loaders.
• setWebViewLayout(options) resizes or insets the WebView/body so native loaders can sit beside it.
• resetWebViewLayout(options?) restores the original WebView/body layout.
• getState() returns currently visible loader ids.
• configure(options) sets default style, placement, colors, motion, and behavior.

Placement Model

placement controls where the native surface appears:

• fullscreen covers the whole app, optionally translucent.
• center floats a compact loader over the WebView.
• top, bottom, left, and right pin loaders to a safe-area-aware edge.
• chrome style uses a full-width native top bar and pairs well with webView.mode: 'resize'.
• around renders loader motion around the screen frame.
• custom uses an explicit frame for native-plugin or split-view workflows.

Use interactionMode: 'passThrough' when users can keep interacting with the WebView, block when loading should prevent taps, or loaderOnly when only the loader surface should receive touches.

Keep going from @capgo/capacitor-native-loader

If you are using @capgo/capacitor-native-loader to plan native media and interface behavior, connect it with Getting Started for implementation details, @capgo/capacitor-native-navigation for native chrome and WebView layout, @capgo/capacitor-transitions for web route motion, and Using @capgo/capacitor-native-loader for the tutorial.