@capgo/transitions

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

Features

• 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

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

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.

Installation

npm install @capgo/transitions

Quick Start

Vanilla JavaScript / Web Components

<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/transitions';

// Navigate programmatically
const outlet = document.querySelector('cap-router-outlet');
outlet.push(newPageElement);
outlet.pop();
outlet.setRoot(newRootElement);

React

import { useRef, useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/transitions/react';
import '@capgo/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}`);
  };

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

Vue

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

Svelte

<script>
  import { routerOutlet, page, setDirection } from '@capgo/transitions/svelte'
  import '@capgo/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>

Solid

import { onMount, onCleanup } from 'solid-js';
import { useNavigate } from '@solidjs/router';
import { initTransitions, setDirection, setupPage, setupRouterOutlet } from '@capgo/transitions/solid';
import '@capgo/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>
  );
}

Angular

// app.component.ts
import { Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, ViewChild, AfterViewInit } from '@angular/core';
import '@capgo/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]);
  }
}

API Reference

Components

<cap-router-outlet>

Container for page transitions.

| Attribute | Type | Default | Description | | --------------- | ------------------------------ | ---------------- | ---------------------------------------------------------------------------------- | | platform | 'ios' \| 'android' \| 'auto' | 'auto' | Animation style | | duration | number | Platform default | Animation duration in ms | | keep-in-dom | boolean | true | Keep pages in DOM after navigating away | | max-cached | number | 10 | Maximum pages to keep cached | | swipe-gesture | boolean \| 'auto' | 'auto' | Enable edge swipe-back gesture. 'auto' enables only in native iOS Capacitor apps |

Methods:

• push(element, config?) - Navigate forward to new page
• pop(config?) - Navigate back
• setRoot(element, config?) - Replace navigation stack
• 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.

<cap-page>

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

<cap-header>

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

<cap-content>

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

| Attribute | Type | Default | Description | | ------------ | --------- | ------- | ----------------------------- | | fullscreen | boolean | false | Content scrolls behind header | | scroll-x | boolean | true | Enable horizontal scroll | | scroll-y | boolean | true | Enable vertical scroll |

<cap-footer>

Footer container. Use with slot="footer".

Transition Directions

| Direction | Description | | ----------- | -------------------------------------- | | 'forward' | Push animation (iOS: slide from right) | | 'back' | Pop animation (iOS: slide to right) | | 'root' | Replace animation (fade) | | 'none' | No animation |

Helper Functions

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

TransitionController

For advanced programmatic control:

import { createTransitionController } from '@capgo/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' });

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

Browser Support

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

Design Philosophy

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.

Examples

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

React Example

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

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

License

MIT