Framework-agnostic page transitions for Capacitor apps. iOS-style navigation without opinions.

• Framework Agnostic - Works with React, Vue, Angular, Svelte, Solid, and any other framework
• iOS & Android Animations - Platform-appropriate transitions out of the box
• Web Animations API - Smooth, GPU-accelerated animations
• View Transitions API - Optional progressive enhancement for supporting browsers
• No Design Opinions - Just transition logic, you bring your own styles
• Coordinated Transitions - Header, content, and footer animate together
• Page Caching - Keep pages in DOM for instant back navigation
• Ionic-style iOS Swipe Back - Optional edge gesture with Capacitor native iOS auto-enable
• Lifecycle Hooks - willEnter, didEnter, willLeave, didLeave events

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

npm install @capgo/capacitor-transitions

<cap-router-outlet platform="auto">
  <cap-page>
    <cap-header slot="header">
      <h1>My Page</h1>
    </cap-header>
    <cap-content slot="content">
      <p>Page content here</p>
    </cap-content>
    <cap-footer slot="footer">
      <nav>Tab bar</nav>
    </cap-footer>
  </cap-page>
</cap-router-outlet>

import '@capgo/capacitor-transitions';

// Navigate programmatically
const outlet = document.querySelector('cap-router-outlet');
outlet.push(newPageElement);
outlet.pop();
outlet.setRoot(newRootElement);
outlet.setRoot(onboardingDoneElement, { direction: 'forward' });

// For router-driven replace/reset flows, reset the stack but keep a forward slide.
outlet.setNavigation('root', 'forward');
yourRouter.replace('/home');

import { useRef, useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import {
  initTransitions,
  setDirection,
  setNavigation,
  setupPage,
  setupRouterOutlet,
} from '@capgo/capacitor-transitions/react';
import '@capgo/capacitor-transitions';

// Initialize once at app startup
initTransitions({ platform: 'auto' });

function App() {
  const outletRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (outletRef.current) {
      setupRouterOutlet(outletRef.current, { platform: 'auto', swipeGesture: 'auto' });
    }
  }, []);

  return (
    <cap-router-outlet ref={outletRef}>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/details/:id" element={<DetailsPage />} />
      </Routes>
    </cap-router-outlet>
  );
}

function HomePage() {
  const navigate = useNavigate();
  const pageRef = useRef<HTMLElement>(null);

  useEffect(() => {
    if (pageRef.current) {
      return setupPage(pageRef.current, {
        onDidEnter: () => console.log('entered'),
      });
    }
  }, []);

  const goToDetails = (id: number) => {
    setDirection('forward');
    navigate(`/details/${id}`);
  };

  const finishOnboarding = () => {
    setNavigation('root', 'forward');
    navigate('/home', { replace: true });
  };

  return (
    <cap-page ref={pageRef}>
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button onClick={() => goToDetails(1)}>Go to Details</button>
      </cap-content>
      <cap-footer slot="footer">
        <nav>Tab bar</nav>
      </cap-footer>
    </cap-page>
  );
}

Importing from @capgo/capacitor-transitions/react registers the web components and includes React JSX typings for cap-router-outlet, cap-page, cap-header, cap-content, and cap-footer. In most React projects, the import in the example above is enough.

If TypeScript still shows Property 'cap-router-outlet' does not exist on type 'JSX.IntrinsicElements', add a project declaration file:

// src/capgo-transitions.d.ts
import '@capgo/capacitor-transitions/react';

Then make sure TypeScript includes it:

{
  "include": ["src", "src/capgo-transitions.d.ts"]
}

For Vite, Create React App, and most webpack React apps, putting capgo-transitions.d.ts inside src/ is enough. For Next.js, put it in src/ or the project root and keep it included in tsconfig.json. For custom TypeScript or webpack setups with a separate types/ folder, add that folder to tsconfig.json:

{
  "include": ["src", "types"]
}

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';
import { useRouter } from 'vue-router';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/vue';
import '@capgo/capacitor-transitions';

// Initialize once
initTransitions({ platform: 'auto' });

const router = useRouter();
const outletRef = ref(null);
const pageRef = ref(null);
let cleanup;

onMounted(() => {
  if (outletRef.value) {
    setupRouterOutlet(outletRef.value, { platform: 'auto' });
  }
  if (pageRef.value) {
    cleanup = setupPage(pageRef.value, {
      onDidEnter: () => console.log('entered'),
    });
  }
});

onUnmounted(() => cleanup?.());

const goToDetails = (id) => {
  setDirection('forward');
  router.push(`/details/${id}`);
};
</script>

<template>
  <cap-router-outlet ref="outletRef">
    <cap-page ref="pageRef">
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button @click="goToDetails(1)">Go to Details</button>
      </cap-content>
    </cap-page>
  </cap-router-outlet>
</template>

<script>
  import { routerOutlet, page, setDirection } from '@capgo/capacitor-transitions/svelte'
  import '@capgo/capacitor-transitions'

  function navigate(to, direction = 'forward') {
    setDirection(direction)
    // Use your router's navigate function
  }
</script>

<cap-router-outlet use:routerOutlet>
  <cap-page use:page={{ onDidEnter: () => console.log('entered') }}>
    <cap-header slot="header">
      <h1>Home</h1>
    </cap-header>
    <cap-content slot="content">
      <button on:click={() => navigate('/details/1')}>Go to Details</button>
    </cap-content>
  </cap-page>
</cap-router-outlet>

import { onMount, onCleanup } from 'solid-js';
import { useNavigate } from '@solidjs/router';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/capacitor-transitions/solid';
import '@capgo/capacitor-transitions';

// Initialize once
initTransitions({ platform: 'auto' });

function HomePage() {
  const navigate = useNavigate();
  let pageRef;

  onMount(() => {
    if (pageRef) {
      const cleanup = setupPage(pageRef, {
        onDidEnter: () => console.log('entered'),
      });
      onCleanup(cleanup);
    }
  });

  const goToDetails = (id) => {
    setDirection('forward');
    navigate(`/details/${id}`);
  };

  return (
    <cap-page ref={pageRef}>
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button onClick={() => goToDetails(1)}>Go to Details</button>
      </cap-content>
    </cap-page>
  );
}

// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import '@capgo/capacitor-transitions';

@Component({
  selector: 'app-root',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-router-outlet #outlet platform="auto">
      <router-outlet></router-outlet>
    </cap-router-outlet>
  `,
})
export class AppComponent {}

// home.component.ts
@Component({
  selector: 'app-home',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <cap-page>
      <cap-header slot="header">
        <h1>Home</h1>
      </cap-header>
      <cap-content slot="content">
        <button (click)="goToDetails(1)">Go to Details</button>
      </cap-content>
    </cap-page>
  `,
})
export class HomeComponent {
  constructor(private router: Router) {}

  goToDetails(id: number) {
    this.router.navigate(['/details', id]);
  }
}

Use @capgo/native-navigation when the native layer should own the navbar or tabbar, and use @capgo/capacitor-transitions for the WebView page content underneath that native chrome.

npm install @capgo/capacitor-transitions @capgo/native-navigation
npx cap sync

Configure native chrome first:

import { NativeNavigation } from '@capgo/native-navigation';

await NativeNavigation.configure({
  contentInsetMode: 'css',
});

await NativeNavigation.setNavbar({
  title: 'Inbox',
  backButton: { visible: false },
});

Keep the transition outlet focused on pages, not native bars:

<cap-router-outlet platform="auto" swipe-gesture="auto">
  <cap-page>
    <cap-content slot="content" fullscreen>
      <main class="native-page">Inbox content</main>
    </cap-content>
  </cap-page>
</cap-router-outlet>

.native-page {
  padding-top: var(--cap-native-navigation-top);
  padding-bottom: var(--cap-native-navigation-bottom);
}

Drive both packages from the same router actions:

import { NativeNavigation } from '@capgo/native-navigation';
import { setDirection, setNavigation } from '@capgo/capacitor-transitions/react';
import { router } from './router';

await NativeNavigation.addListener('navbarBack', () => {
  setDirection('back');
  router.back();
});

async function openMessage(id: string) {
  setDirection('forward');
  router.push(`/message/${id}`);

  await NativeNavigation.setNavbar({
    title: 'Message',
    backButton: { visible: true, title: 'Inbox' },
  });
}

async function finishOnboarding() {
  setNavigation('root', 'forward');
  router.replace('/inbox');

  await NativeNavigation.setNavbar({
    title: 'Inbox',
    backButton: { visible: false },
  });
}

Do not render the native top bar again as a moving <cap-header>. Native Navigation keeps the bar native; this package animates the web page body.

Container for page transitions.

Methods:

• push(element, config?) - Navigate forward to new page
• pop(config?) - Navigate back
• setRoot(element, config?) - Replace navigation stack. Pass { direction: 'forward' } to reset the stack with a forward slide.
• setNavigation(action, direction?) - Set the stack action and animation direction for the next router-driven navigation
• setSwipeGesture(true | false | 'auto') - Enable, disable, or auto-detect edge swipe-back gesture

swipe-gesture="auto" uses Capacitor's runtime helpers (Capacitor.isNativePlatform() and Capacitor.getPlatform()) and enables the gesture only for native iOS apps. Use swipe-gesture="true" to force it on any platform or swipe-gesture="false" to disable it.

Page container with header/content/footer slots.

Events:

• cap-will-enter - Before page becomes visible
• cap-did-enter - After page becomes visible
• cap-will-leave - Before page leaves
• cap-did-leave - After page leaves

Header container. Use with slot="header" inside <cap-page>.

Main scrollable content area. Use with slot="content".

Footer container. Use with slot="footer".

Navigation actions control the recorded stack independently from the visual animation. This is useful when a router replace or native navigation reset should feel like a forward page push but must not leave a swipe-back entry behind.

setNavigation('root', 'forward');
router.replace('/home');

setNavigation('root', 'forward') clears the transition stack after the navigation and plays the forward animation. Swipe-back stays disabled because there is no previous page.

All framework bindings export these helper functions:

// Initialize the transition system
initTransitions({ platform: 'auto' });

// Set the direction for the next navigation
setDirection('forward' | 'back' | 'root' | 'none');

// Set the stack action and animation direction for the next navigation
setNavigation('root', 'forward');
setNavigation('root'); // direction is optional and defaults to the same value as the stack action.

// Set up a router outlet element
setupRouterOutlet(element, options);

// Auto-enable the iOS edge swipe-back gesture in native Capacitor iOS apps
setupRouterOutlet(element, { swipeGesture: 'auto' });

// Force enable or disable from JavaScript
setupRouterOutlet(element, { swipeGesture: true });
setupRouterOutlet(element, { swipeGesture: false });

// Set up a page element with lifecycle callbacks (returns cleanup function)
setupPage(element, { onWillEnter, onDidEnter, onWillLeave, onDidLeave });

// Create a transition-aware navigate function
const transitionNavigate = createTransitionNavigate(navigate);
transitionNavigate('/path', 'forward');

For advanced programmatic control:

import { createTransitionController } from '@capgo/capacitor-transitions';

const controller = createTransitionController({
  platform: 'auto',
  duration: 400,
  useViewTransitions: true,
});

// Navigate
await controller.push(element, { direction: 'forward' });
await controller.pop({ direction: 'back' });
await controller.setRoot(element, { direction: 'root' });
await controller.setRoot(element, { direction: 'forward' });

// Lifecycle hooks
controller.registerLifecycle('page-id', {
  onWillEnter: (event) => console.log('Will enter', event),
  onDidEnter: (event) => console.log('Did enter', event),
  onWillLeave: (event) => console.log('Will leave', event),
  onDidLeave: (event) => console.log('Did leave', event),
});

• Modern browsers with Web Animations API support
• Optional View Transitions API (Chrome 111+, Edge 111+, Safari 18+) support
• Graceful fallback for older browsers

This library is intentionally unopinionated about styling:

1. Minimal structural CSS - You bring your own visual system
2. No design system - Works with any UI library or custom styles
3. Just transitions - Focus on smooth page navigation
4. Framework agnostic - Use with React, Vue, Angular, Svelte, Solid, or vanilla JS

The goal is to provide Ionic-quality page transitions without Ionic's design system or framework lock-in.

See the /examples directory for complete examples:

• react-app - React with React Router
• vue-app - Vue 3 with Vue Router
• angular-app - Angular with Angular Router
• svelte-app - Svelte 5
• solid-app - Solid with Solid Router
• tanstack-app - React with TanStack Router

The React example demonstrates iOS-style page transitions with smooth animations:

Home Page

Details Page

Nested Page

Features demonstrated:

• Forward navigation with slide-in animation
• Back navigation with slide-out animation
• Multi-level page stack
• Coordinated header/content/footer transitions

To run the React example:

cd examples/react-app
npm install
npm run dev

MIT