@capgo/capacitor-transitions

Ionic-style motion

Use iOS and Android route animations modeled after mobile navigation patterns without shipping Ionic components.

Swipe back

Enable an iOS edge gesture that follows the finger and can auto-enable only inside native Capacitor iOS.

Framework agnostic

Use web components directly or helpers for React, Vue, Angular, Svelte, and Solid.

No UI lock-in

Bring your own toolbar, content, footer, and router while the library coordinates transition layers.

When To Use It

@capgo/capacitor-transitions is for apps that want Ionic-quality page motion without adopting Ionic’s component system. It keeps navigation in your existing web router and animates page elements inside the Capacitor WebView.

Use it when you need:

• push, pop, and root route transitions that feel close to platform conventions
• coordinated header, content, and footer motion
• page caching for fast back navigation
• an optional iOS edge swipe-back gesture that follows the user’s finger
• framework-specific setup helpers without a framework-specific router

Note

This package does not render native UIKit or Android navigation chrome. For native navbars, tabbars, and native transition shells, use @capgo/native-navigation.

Core API

• <cap-router-outlet> owns the animated route stack.
• <cap-page> wraps each page.
• <cap-header>, <cap-content>, and <cap-footer> identify the regions that should move together.
• initTransitions(options?) initializes framework bindings.
• setDirection('forward' | 'back' | 'root' | 'none') tells the next router update which animation to run.
• setupRouterOutlet(element, options?) connects an outlet to lifecycle and gesture behavior.
• setupPage(element, callbacks?) registers page lifecycle callbacks.

Platform Model

platform="auto" chooses the iOS or Android animation profile from the runtime environment. You can force platform="ios" or platform="android" when testing.

swipe-gesture="auto" uses Capacitor runtime helpers and enables the edge gesture only in native iOS Capacitor apps. Use true to force it on or false to disable it.

The gesture is implemented in the web layer. It is designed to feel like Ionic’s iOS swipe-back transition by driving animation progress from the pointer position, then finishing or cancelling based on distance and velocity.