Primeros pasos

Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-native-navigation`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/native-navigation/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Instalación

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego usa el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-navigation` plugin in my project.

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

Instala el paquete

npm i @capgo/capacitor-native-navigation

Sincronizar proyectos nativos
Ventana de terminal
```
npx cap sync
```

Configurar el chrome nativo

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

await NativeNavigation.configure({
  contentInsetMode: 'css',
  animationDuration: 360,
  colors: {
    tint: '#0f172a',
    inactiveTint: '#64748b',
  },
});

Renderizar la navbar nativa

await NativeNavigation.setNavbar({
  title: 'Home',
  subtitle: 'Native chrome',
  transparent: true,
  backButton: { visible: false },
  rightItems: [
    {
      id: 'compose',
      title: 'Compose',
      icon: {
        svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z"/></svg>',
      },
    },
  ],
});

Renderizar la tabbar nativa

await NativeNavigation.setTabbar({
  selectedId: 'home',
  labelVisibilityMode: 'selected',
  icons: true,
  colors: {
    dynamic: true,
    tint: '#0f172a',
    inactiveTint: '#64748b',
  },
  tabs: [
    {
      id: 'home',
      title: 'Home',
      icon: {
        svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 10.5 12 3l9 7.5"/><path d="M5 10v10h14V10"/></svg>',
      },
    },
    {
      id: 'settings',
      title: 'Settings',
      badge: '2',
      icon: {
        svg: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="3"/><path d="M12 2v3M12 19v3M2 12h3M19 12h3"/></svg>',
      },
    },
  ],
});

Gestionar eventos de intent nativos

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

await NativeNavigation.addListener('navbarItemTap', ({ id }) => {
  if (id === 'compose') router.push('/compose');
});

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  router.push(`/${id}`);
});

Pasa segments a setNavbar para apilar filas de segmentos nativos bajo la barra; por ejemplo, un selector de scope arriba y pestañas de sección debajo. Las filas se dibujan de arriba hacia abajo y cada una añade 44pt (iOS) o 48dp (Android) a la navbar y a los insets reportados. iOS usa UISegmentedControl y cápsulas de cristal; Android usa botones segmentados de Material y filter chips.

iOS	Android

const sections = {
  account: ['General', 'Notifications', 'Password', 'Two-factor'],
  organization: ['General', 'Members', 'Plans', 'Usage', 'Credits', 'Billing', 'Security', 'Webhooks'],
};
const selection = { scope: 'account', section: 'general' };

const renderNavbar = () =>
  NativeNavigation.setNavbar({
    title: 'Settings',
    segments: [
      {
        id: 'scope',
        selectedId: selection.scope,
        items: [
          { id: 'account', title: 'Account' },
          { id: 'organization', title: 'Organization' },
        ],
      },
      {
        id: 'section',
        style: 'scroll', // scrolling chips; `auto` uses `segmented` for up to 4 items
        selectedId: selection.section,
        items: sections[selection.scope].map((title) => ({ id: title.toLowerCase(), title })),
      },
    ],
  });

await NativeNavigation.addListener('navbarSegmentSelect', async ({ groupId, id }) => {
  if (groupId === 'scope') {
    selection.scope = id;
    selection.section = 'general'; // the second level depends on the first one
  } else {
    selection.section = id;
  }
  await renderNavbar();
});

await renderNavbar();

La selección se mueve de forma nativa al tocar, pero cada setNavbar llamada aplica selectedId de nuevo. Mantén los ids seleccionados en tu estado y pásalos en cada setNavbar llamada posterior; para rechazar una selección, envía el anterior selectedId. Los items también aceptan icon, accessibilityLabel, y enabled. Pass segments: [] para eliminar las filas. Disponible desde la 8.13.0.

Flujo de transición

Las transiciones nativas son una transacción alrededor de tu cambio de ruta de JavaScript habitual:

const transition = await NativeNavigation.beginTransition({
  direction: 'forward',
});

router.push('/detail');
await router.ready?.();

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

await NativeNavigation.finishTransition({
  id: transition.id,
  direction: 'forward',
});

Transición de zoom

Usa los helpers de zoom para flujos de tarjeta a detalle o vista previa de medios. Pasa el elemento pulsado antes de que el router cambie el contenido, y finaliza cuando la página de detalle esté lista.

import { beginZoomTransition, finishZoomTransition } from '@capgo/capacitor-native-navigation';

const card = document.querySelector('[data-message-card]');
if (card) {
  const transition = await beginZoomTransition(card, { cornerRadius: 18 });

  router.push('/message/42');
  await router.ready?.();

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

  await finishZoomTransition(undefined, {
    id: transition.id,
    cornerRadius: 18,
  });
}

Usar con @capgo/capacitor-transitions

Usa Native Navigation para la navbar, tabbar, safe-area insets y eventos de intent nativos. Usa @capgo/capacitor-transitions para el stack de páginas del WebView bajo el chrome nativo.

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

Inicializa ambos paquetes una vez:

import { NativeNavigation } from '@capgo/capacitor-native-navigation';
import '@capgo/capacitor-transitions';
import { initTransitions, setupRouterOutlet, setDirection } from '@capgo/capacitor-transitions/react';

initTransitions({ platform: 'auto' });

const outlet = document.querySelector('cap-router-outlet');
if (outlet) {
  setupRouterOutlet(outlet, { platform: 'auto', swipeGesture: 'auto' });
}

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

Mantén cap-router-outlet centrado en páginas, no en barras web duplicadas:

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

Controla ambos paquetes desde las mismas acciones del router:

async function openMessage(id: string) {
  setDirection('forward');
  await router.push(`/messages/${id}`);
  await NativeNavigation.setNavbar({
    title: 'Message',
    backButton: { visible: true, title: 'Inbox' },
  });
}

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

await NativeNavigation.addListener('tabSelect', ({ id }) => {
  setDirection('root');
  router.push(`/${id}`);
});

Elige una capa de animación por cambio de ruta. Deja @capgo/capacitor-transitions que se animen los push normales y usa los helpers de zoom de Native Navigation solo para shared element/zoom.

Insets de CSS

Con contentInsetMode: 'css', el plugin escribe las dimensiones de la barra nativa en document.documentElement.

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

Variables disponibles:

--cap-native-navigation-top
--cap-native-navigation-right
--cap-native-navigation-bottom
--cap-native-navigation-left
--cap-native-navbar-height
--cap-native-tabbar-height

Descriptores de iconos

Los iconos deben ser serializables porque la UI nativa los renderiza. Puedes usar SVG multiplataforma, SVG específico de plataforma, SF Symbols, imágenes de iOS incluidas en el bundle, recursos drawable de Android o imágenes de Android incluidas en el bundle.

const icon = {
  svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
  width: 24,
  height: 24,
  template: true,
  src: 'fallback_asset_name',
  ios: {
    svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
    sfSymbol: 'house.fill',
    image: 'BundledAssetName',
  },
  android: {
    svg: '<svg viewBox="0 0 24 24"><path d="M3 10.5 12 3l9 7.5"/></svg>',
    resource: 'ic_menu_view',
    image: 'bundled_drawable_name',
  },
};

El SVG inline admite el subconjunto centrado en iconos que usan sets de iconos comunes como Lucide y Feather: path, line, polyline, polygon, circle, y rect. Los iconos SVG se renderizan como template images por defecto, así que los colores de tinte nativos pueden recolorearlos.

Web components opcionales

El paquete puede registrar custom elements para una configuración declarativa agnóstica al framework:

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

defineNativeNavigationElements();

<cap-native-navigation-provider enabled="true" content-inset-mode="css"></cap-native-navigation-provider>

<cap-native-navbar
  title="Home"
  transparent
  right-items='[{"id":"compose","title":"Compose","icon":{"svg":"<svg viewBox=\"0 0 24 24\"><path d=\"M12 20h9\"/></svg>"}}]'
></cap-native-navbar>

<cap-native-tabbar
  selected-id="home"
  tabs='[{"id":"home","title":"Home","icon":{"ios":{"sfSymbol":"house.fill"}}}]'
></cap-native-tabbar>

iPhone Duo (iOS 27)

En iPhone Duo, iOS suele colocar la barra de pestañas del sistema y la barra de estado en un barra lateral vertical. env(safe-area-inset-top) pueden ser 0 mientras left o right crece. Configura viewport-fit=cover en tu meta tag de viewport cuando uses padding con CSS env en cualquier parte de la app. Prueba los estados plegado, abierto, landscape y Split View en Xcode Device Hub.

Native Navigation utiliza UINavigationBar y UITabBar, así que las system tab bars siguen el rail. El curva la forma de la tab bar se mantiene abajo; la acción central mantiene un cradle circular cuando la ventana se expande.

Dos layouts landscape abiertos. A la izquierda, la system tab bar está en el side rail. A la derecha, la tab bar curva se mantiene abajo y la acción central está en un cradle circular.

Con contentInsetMode: 'css', añade padding al contenido web con variables del plugin. Usa max() con fallbacks de env por edge para que el layout sea correcto cuando una variable de plugin sea 0 sin sumar insets duplicados:

main {
  padding-top: max(var(--cap-native-navigation-top, 0px), env(safe-area-inset-top, 0px));
  padding-right: max(var(--cap-native-navigation-right, 0px), env(safe-area-inset-right, 0px));
  padding-bottom: max(var(--cap-native-navigation-bottom, 0px), env(safe-area-inset-bottom, 0px));
  padding-left: max(var(--cap-native-navigation-left, 0px), env(safe-area-inset-left, 0px));
}

Escucha safeAreaChanged (o capNativeNavigation:safeAreaChanged en window) cuando cambia el estado del fold o del rail. En tab bars de sistemas alojados, insets.tabbarHeight podría ser 0 para evitar el doble padding inferior; usa insets.systemTabbarHeight o --cap-native-system-tabbar-height para los offsets de FAB.

Guía sobre Capacitor (viewport-fit, System Bars, Status Bar, testing): Soporte para iPhone Duo en apps Capacitor.

Notas de plataforma

Renderizado en iOS UINavigationBar y UITabBar; iOS 26+ usa el comportamiento de la barra Liquid Glass del sistema.
Android renderiza una toolbar AppCompat y una Material bottom navigation.
El fallback de Web no dibuja barras nativas. Refleja eventos y variables de insets para el desarrollo en navegador.
El plugin mantiene un Capacitor WebView a pantalla completa. El entorno nativo gestiona el frame, las barras, el reporte de safe-area y el shell de transición.

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar el comportamiento de los medios nativos y la interfaz, conéctalo con Uso de @capgo/capacitor-native-navigation para la capacidad nativa en Uso de @capgo/capacitor-native-navigation, Uso de @capgo/capacitor-live-activities para la capacidad nativa en Uso de @capgo/capacitor-live-activities, @capgo/capacitor-live-activities para los detalles de implementación en @capgo/capacitor-live-activities, Uso de @capgo/capacitor-video-player para la capacidad nativa en Uso de @capgo/capacitor-video-player, y @capgo/capacitor-video-player para el detalle de implementación en @capgo/capacitor-video-player.