{"id":49753389,"url":"https://github.com/cap-go/capacitor-native-navigation","last_synced_at":"2026-05-16T15:00:54.220Z","repository":{"id":356903941,"uuid":"1234535294","full_name":"Cap-go/capacitor-native-navigation","owner":"Cap-go","description":"Capacitor plugin for Liquid glass native navigation tabs","archived":false,"fork":false,"pushed_at":"2026-05-14T17:42:01.000Z","size":4193,"stargazers_count":5,"open_issues_count":3,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T14:26:24.967Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://capgo.app/docs/plugins/native-navigation/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cap-go.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"Cap-go","patreon":null,"open_collective":"capgo","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2026-05-10T10:07:58.000Z","updated_at":"2026-05-15T11:52:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Cap-go/capacitor-native-navigation","commit_stats":null,"previous_names":["cap-go/capacitor-native-navigation"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/Cap-go/capacitor-native-navigation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-native-navigation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-native-navigation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-native-navigation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-native-navigation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cap-go","download_url":"https://codeload.github.com/Cap-go/capacitor-native-navigation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cap-go%2Fcapacitor-native-navigation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33107564,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-10T15:02:41.265Z","updated_at":"2026-05-16T15:00:54.172Z","avatar_url":"https://github.com/Cap-go.png","language":"Swift","funding_links":["https://github.com/sponsors/Cap-go","https://opencollective.com/capgo"],"categories":[],"sub_categories":[],"readme":"# @capgo/capacitor-native-navigation\n\u003ca href=\"https://capgo.app/\"\u003e\u003cimg src=\"https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-native-navigation\" alt=\"Capgo - Instant updates for Capacitor\" /\u003e\u003c/a\u003e\n\n\u003cdiv align=\"center\"\u003e\n \u003ch2\u003e\u003ca href=\"https://capgo.app/?ref=plugin_native_navigation\"\u003eGet instant updates for your app with Capgo\u003c/a\u003e\u003c/h2\u003e\n \u003ch2\u003e\u003ca href=\"https://capgo.app/consulting/?ref=plugin_native_navigation\"\u003eMissing a feature? We can build the plugin for you\u003c/a\u003e\u003c/h2\u003e\n\u003c/div\u003e\n\nNative navigation chrome for Capacitor apps. Render a native navbar, native tabbar, and native transition shell over a single full-screen WebView while your framework keeps owning routes and content.\n\n## Demo\n\n### Native navigation tap flow\n\n\u003cimg src=\"./docs/demo-navigation.webp\" alt=\"Animated native navigation tap flow showing tab selection, push transition, and native back\" width=\"320\" /\u003e\n\n### SVG icon descriptors\n\n\u003cimg src=\"./docs/demo-svg-icons.webp\" alt=\"Animated native SVG icon demo showing inline SVG icons, native tint, labels, and tab selection\" width=\"320\" /\u003e\n\n### Native styling and zoom options\n\n\u003cimg src=\"./docs/demo-options.webp\" alt=\"Animated native navigation options demo showing dynamic colors, selected labels, custom indicators, badges, system Liquid Glass, and zoom transitions\" width=\"320\" /\u003e\n\n## What It Does\n\n- Renders native top navigation and bottom tab chrome from JavaScript state.\n- Emits native intent events such as `navbarBack`, `navbarItemTap`, and `tabSelect`.\n- Captures WebView snapshots for native-feeling push, back, root, tab, and zoom transition shells.\n- Supports native tab styling controls such as Material You dynamic colors, label visibility, indicators, ripples, badges, and selected icons.\n- Writes CSS variables so web content can scroll behind native bars without being hidden.\n- Works with React, Vue, Angular, Svelte, Solid, vanilla JS, and any router that can call imperative methods.\n\n## What It Does Not Do\n\n- It does not create one native WebView per route.\n- It does not render React/Vue/Svelte icon nodes natively. Icons must be serializable descriptors such as SVG strings, SF Symbols, or native resource names.\n- It does not replace your router. JS still owns route state and web content rendering.\n\n## Compatibility\n\n| Plugin version | Capacitor compatibility | Maintained |\n| -------------- | ----------------------- | ---------- |\n| v8.\\*.\\* | v8.\\*.\\* | Yes |\n| v7.\\*.\\* | v7.\\*.\\* | On demand |\n| v6.\\*.\\* | v6.\\*.\\* | On demand |\n\n## Install\n\n```bash\nbun add @capgo/capacitor-native-navigation\nbunx cap sync\n```\n\n## Minimal Usage\n\n```typescript\nimport { NativeNavigation } from '@capgo/capacitor-native-navigation';\n\nawait NativeNavigation.configure({\n contentInsetMode: 'css',\n animationDuration: 360,\n});\n\nawait NativeNavigation.setNavbar({\n title: 'Home',\n subtitle: 'Native chrome',\n transparent: true,\n backButton: { visible: false },\n rightItems: [\n {\n id: 'compose',\n title: 'Compose',\n icon: {\n svg: '\u003csvg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"\u003e\u003cpath d=\"M12 20h9\"/\u003e\u003cpath d=\"M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z\"/\u003e\u003c/svg\u003e',\n },\n },\n ],\n});\n\nawait NativeNavigation.setTabbar({\n selectedId: 'home',\n labelVisibilityMode: 'labeled',\n icons: true,\n colors: {\n dynamic: true,\n },\n tabs: [\n {\n id: 'home',\n title: 'Home',\n icon: {\n svg: '\u003csvg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"\u003e\u003cpath d=\"M3 10.5 12 3l9 7.5\"/\u003e\u003cpath d=\"M5 10v10h14V10\"/\u003e\u003c/svg\u003e',\n },\n },\n {\n id: 'settings',\n title: 'Settings',\n icon: {\n svg: '\u003csvg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"\u003e\u003ccircle cx=\"12\" cy=\"12\" r=\"3\"/\u003e\u003cpath d=\"M12 2v3M12 19v3M2 12h3M19 12h3\"/\u003e\u003c/svg\u003e',\n },\n },\n ],\n});\n\nNativeNavigation.addListener('tabSelect', ({ id }) =\u003e {\n router.navigate(id);\n});\n```\n\n## Native Tab Styling\n\n```typescript\nawait NativeNavigation.setTabbar({\n selectedId: 'home',\n labelVisibilityMode: 'selected',\n indicatorColor: '#0A84FF',\n rippleColor: '#330A84FF',\n badgeBackgroundColor: '#FF3B30',\n badgeTextColor: '#FFFFFF',\n colors: {\n dynamic: true,\n tint: '#0A84FF',\n inactiveTint: '#8E8E93',\n },\n tabs: [\n {\n id: 'home',\n title: 'Home',\n icon: { ios: { sfSymbol: 'house' }, android: { resource: 'ic_home' } },\n selectedIcon: { ios: { sfSymbol: 'house.fill' }, android: { resource: 'ic_home_filled' } },\n },\n ],\n});\n```\n\n## Transition Flow\n\n```typescript\nconst transition = await NativeNavigation.beginTransition({ direction: 'forward' });\n\nrouter.navigate('/detail');\nawait router.ready?.();\n\nawait NativeNavigation.setNavbar({\n title: 'Detail',\n backButton: { visible: true, title: 'Back' },\n});\n\nawait NativeNavigation.finishTransition({\n id: transition.id,\n direction: 'forward',\n});\n```\n\n## Use With @capgo/capacitor-transitions\n\nUse `@capgo/capacitor-native-navigation` for the native navbar, tabbar, safe-area insets, and native intent events. Use `@capgo/capacitor-transitions` for the WebView page stack underneath that native chrome.\n\n```bash\nnpm install @capgo/capacitor-native-navigation @capgo/capacitor-transitions\nnpx cap sync\n```\n\nInitialize both packages once when the app starts:\n\n```typescript\nimport { NativeNavigation } from '@capgo/capacitor-native-navigation';\nimport '@capgo/capacitor-transitions';\nimport { initTransitions, setupRouterOutlet, setDirection } from '@capgo/capacitor-transitions/react';\n\ninitTransitions({ platform: 'auto' });\n\nconst outlet = document.querySelector('cap-router-outlet');\nif (outlet) {\n setupRouterOutlet(outlet, { platform: 'auto', swipeGesture: 'auto' });\n}\n\nawait NativeNavigation.configure({\n contentInsetMode: 'css',\n});\n```\n\nKeep the transition outlet focused on pages. Do not render a web header or footer when native chrome owns those surfaces:\n\n```html\n\u003ccap-router-outlet platform=\"auto\" swipe-gesture=\"auto\"\u003e\n \u003ccap-page\u003e\n \u003ccap-content slot=\"content\" fullscreen\u003e\n \u003cmain class=\"page\"\u003eInbox content\u003c/main\u003e\n \u003c/cap-content\u003e\n \u003c/cap-page\u003e\n\u003c/cap-router-outlet\u003e\n```\n\n```css\n.page {\n min-height: 100dvh;\n padding-top: var(--cap-native-navigation-top);\n padding-bottom: var(--cap-native-navigation-bottom);\n}\n```\n\nDrive both packages from the same router actions:\n\n```typescript\nasync function openMessage(id: string) {\n setDirection('forward');\n await router.push(`/messages/${id}`);\n await NativeNavigation.setNavbar({\n title: 'Message',\n backButton: { visible: true, title: 'Inbox' },\n });\n}\n\nawait NativeNavigation.addListener('navbarBack', () =\u003e {\n setDirection('back');\n router.back();\n});\n\nawait NativeNavigation.addListener('tabSelect', ({ id }) =\u003e {\n setDirection('root');\n router.push(`/${id}`);\n});\n```\n\nPick one animation layer per navigation. For normal route pushes, let `@capgo/capacitor-transitions` animate the WebView pages and update native bars with `setNavbar` / `setTabbar`. For shared-element or zoom routes, use `beginZoomTransition` / `finishZoomTransition` from this plugin and skip the web page transition for that navigation.\n\n## Zoom Transition\n\n```typescript\nimport { beginZoomTransition, finishZoomTransition } from '@capgo/capacitor-native-navigation';\n\nconst card = document.querySelector('[data-photo-card]');\nif (card) {\n const transition = await beginZoomTransition(card, { cornerRadius: 18 });\n\n router.navigate('/photo/42');\n await router.ready?.();\n\n await finishZoomTransition(undefined, {\n id: transition.id,\n cornerRadius: 18,\n });\n}\n```\n\n## CSS Insets\n\nWith `contentInsetMode: 'css'`, the plugin updates these variables on `document.documentElement`:\n\n```css\n.app-scroll {\n height: 100dvh;\n overflow: auto;\n padding-top: calc(var(--cap-native-navigation-top) + 24px);\n scroll-padding-bottom: calc(var(--cap-native-navigation-bottom) + 24px);\n}\n\n.page {\n min-height: 100dvh;\n padding-bottom: calc(var(--cap-native-navigation-bottom) + 24px);\n}\n```\n\nAvailable variables:\n\n- `--cap-native-navigation-top`\n- `--cap-native-navigation-right`\n- `--cap-native-navigation-bottom`\n- `--cap-native-navigation-left`\n- `--cap-native-navbar-height`\n- `--cap-native-tabbar-height`\n\n## Web Components\n\nThe package can register optional custom elements for framework-agnostic declarative setup:\n\n```typescript\nimport { defineNativeNavigationElements } from '@capgo/capacitor-native-navigation';\n\ndefineNativeNavigationElements();\n```\n\n```html\n\u003ccap-native-navigation-provider enabled=\"true\" content-inset-mode=\"css\"\u003e\u003c/cap-native-navigation-provider\u003e\n\n\u003ccap-native-navbar\n title=\"Home\"\n subtitle=\"Native chrome\"\n transparent\n right-items='[{\"id\":\"compose\",\"title\":\"Compose\",\"icon\":{\"ios\":{\"sfSymbol\":\"square.and.pencil\"}}}]'\n\u003e\u003c/cap-native-navbar\u003e\n\n\u003ccap-native-tabbar\n selected-id=\"home\"\n tabs='[{\"id\":\"home\",\"title\":\"Home\",\"icon\":{\"ios\":{\"sfSymbol\":\"house.fill\"}}}]'\n\u003e\u003c/cap-native-tabbar\u003e\n```\n\n## Icon Descriptors\n\n```typescript\nconst icon = {\n svg: '\u003csvg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\"\u003e\u003cpath d=\"M3 10.5 12 3l9 7.5\"/\u003e\u003c/svg\u003e',\n width: 24,\n height: 24,\n template: true,\n src: 'fallback_asset_name',\n ios: {\n svg: '\u003csvg viewBox=\"0 0 24 24\"\u003e\u003cpath d=\"M3 10.5 12 3l9 7.5\"/\u003e\u003c/svg\u003e',\n sfSymbol: 'house.fill',\n image: 'BundledAssetName',\n },\n android: {\n svg: '\u003csvg viewBox=\"0 0 24 24\"\u003e\u003cpath d=\"M3 10.5 12 3l9 7.5\"/\u003e\u003c/svg\u003e',\n resource: 'ic_menu_view',\n image: 'bundled_drawable_name',\n },\n};\n```\n\nInline SVG supports the icon-focused subset used by common sets such as Lucide and Feather: `path`, `line`, `polyline`, `polygon`, `circle`, and `rect`. The SVG is rendered as a template image by default, so native tint colors can recolor it without bundling a platform asset.\n\n## Platform Notes\n\n- iOS uses UIKit `UINavigationBar` and `UITabBar`. iOS 26+ hosts the tabbar in a real `UITabBarController` so Apple owns the system Liquid Glass background; earlier versions use native translucent/material fallback styling.\n- Android uses an AppCompat `Toolbar` and a floating native tab capsule with edge-to-edge placement.\n- Web fallback does not draw native bars; it mirrors inset variables and events for development.\n\n## Example App\n\nThe `example-app/` folder is a vanilla JS Capacitor demo linked with `file:..`.\n\n```bash\ncd example-app\nbun install\nbun run build\nbunx cap add ios\nbunx cap add android\nbunx cap sync\n```\n\n## API\n\n\u003cdocgen-index\u003e\n\n* [`configure(...)`](#configure)\n* [`setNavbar(...)`](#setnavbar)\n* [`setTabbar(...)`](#settabbar)\n* [`beginTransition(...)`](#begintransition)\n* [`finishTransition(...)`](#finishtransition)\n* [`getPluginVersion()`](#getpluginversion)\n* [`addListener('navbarBack', ...)`](#addlistenernavbarback-)\n* [`addListener('navbarItemTap', ...)`](#addlistenernavbaritemtap-)\n* [`addListener('tabSelect', ...)`](#addlistenertabselect-)\n* [`addListener('safeAreaChanged', ...)`](#addlistenersafeareachanged-)\n* [`addListener('transitionStart', ...)`](#addlistenertransitionstart-)\n* [`addListener('transitionEnd', ...)`](#addlistenertransitionend-)\n* [Interfaces](#interfaces)\n* [Type Aliases](#type-aliases)\n\n\u003c/docgen-index\u003e\n\n\u003cdocgen-api\u003e\n\u003c!--Update the source file JSDoc comments and rerun docgen to update the docs below--\u003e\n\nFramework-agnostic native navigation chrome API.\n\n### configure(...)\n\n```typescript\nconfigure(options?: NativeNavigationConfigureOptions | undefined) =\u003e Promise\u003cNativeNavigationInsetsResult\u003e\n```\n\nConfigure the native chrome host and content inset behavior.\n\n| Param | Type |\n| ------------- | --------------------------------------------------------------------------------------------- |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#nativenavigationconfigureoptions\"\u003eNativeNavigationConfigureOptions\u003c/a\u003e\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#nativenavigationinsetsresult\"\u003eNativeNavigationInsetsResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### setNavbar(...)\n\n```typescript\nsetNavbar(options: NativeNavigationNavbarOptions) =\u003e Promise\u003cNativeNavigationInsetsResult\u003e\n```\n\nRender or update the native navbar.\n\n| Param | Type |\n| ------------- | --------------------------------------------------------------------------------------- |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#nativenavigationnavbaroptions\"\u003eNativeNavigationNavbarOptions\u003c/a\u003e\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#nativenavigationinsetsresult\"\u003eNativeNavigationInsetsResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### setTabbar(...)\n\n```typescript\nsetTabbar(options: NativeNavigationTabbarOptions) =\u003e Promise\u003cNativeNavigationInsetsResult\u003e\n```\n\nRender or update the native tabbar.\n\n| Param | Type |\n| ------------- | --------------------------------------------------------------------------------------- |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#nativenavigationtabbaroptions\"\u003eNativeNavigationTabbarOptions\u003c/a\u003e\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#nativenavigationinsetsresult\"\u003eNativeNavigationInsetsResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### beginTransition(...)\n\n```typescript\nbeginTransition(options?: NativeNavigationBeginTransitionOptions | undefined) =\u003e Promise\u003cNativeNavigationTransitionResult\u003e\n```\n\nCapture the current WebView and prepare a native transition.\n\n| Param | Type |\n| ------------- | --------------------------------------------------------------------------------------------------------- |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#nativenavigationbegintransitionoptions\"\u003eNativeNavigationBeginTransitionOptions\u003c/a\u003e\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#nativenavigationtransitionresult\"\u003eNativeNavigationTransitionResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### finishTransition(...)\n\n```typescript\nfinishTransition(options?: NativeNavigationFinishTransitionOptions | undefined) =\u003e Promise\u003cNativeNavigationTransitionResult\u003e\n```\n\nAnimate from the captured WebView snapshot to the current live WebView.\n\n| Param | Type |\n| ------------- | ----------------------------------------------------------------------------------------------------------- |\n| **`options`** | \u003ccode\u003e\u003ca href=\"#nativenavigationfinishtransitionoptions\"\u003eNativeNavigationFinishTransitionOptions\u003c/a\u003e\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#nativenavigationtransitionresult\"\u003eNativeNavigationTransitionResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### getPluginVersion()\n\n```typescript\ngetPluginVersion() =\u003e Promise\u003cPluginVersionResult\u003e\n```\n\nReturns the platform implementation version marker.\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginversionresult\"\u003ePluginVersionResult\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### addListener('navbarBack', ...)\n\n```typescript\naddListener(eventName: 'navbarBack', listenerFunc: (event: NativeNavigationBackEvent) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------------------------- |\n| **`eventName`** | \u003ccode\u003e'navbarBack'\u003c/code\u003e |\n| **`listenerFunc`** | \u003ccode\u003e(event: \u003ca href=\"#nativenavigationbackevent\"\u003eNativeNavigationBackEvent\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### addListener('navbarItemTap', ...)\n\n```typescript\naddListener(eventName: 'navbarItemTap', listenerFunc: (event: NativeNavigationBarItemTapEvent) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------------------------------------- |\n| **`eventName`** | \u003ccode\u003e'navbarItemTap'\u003c/code\u003e |\n| **`listenerFunc`** | \u003ccode\u003e(event: \u003ca href=\"#nativenavigationbaritemtapevent\"\u003eNativeNavigationBarItemTapEvent\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### addListener('tabSelect', ...)\n\n```typescript\naddListener(eventName: 'tabSelect', listenerFunc: (event: NativeNavigationTabSelectEvent) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\n| Param | Type |\n| ------------------ | ------------------------------------------------------------------------------------------------------------- |\n| **`eventName`** | \u003ccode\u003e'tabSelect'\u003c/code\u003e |\n| **`listenerFunc`** | \u003ccode\u003e(event: \u003ca href=\"#nativenavigationtabselectevent\"\u003eNativeNavigationTabSelectEvent\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### addListener('safeAreaChanged', ...)\n\n```typescript\naddListener(eventName: 'safeAreaChanged', listenerFunc: (event: NativeNavigationSafeAreaChangedEvent) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\n| Param | Type |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |\n| **`eventName`** | \u003ccode\u003e'safeAreaChanged'\u003c/code\u003e |\n| **`listenerFunc`** | \u003ccode\u003e(event: \u003ca href=\"#nativenavigationsafeareachangedevent\"\u003eNativeNavigationSafeAreaChangedEvent\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### addListener('transitionStart', ...)\n\n```typescript\naddListener(eventName: 'transitionStart', listenerFunc: (event: NativeNavigationTransitionEvent) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------------------------------------- |\n| **`eventName`** | \u003ccode\u003e'transitionStart'\u003c/code\u003e |\n| **`listenerFunc`** | \u003ccode\u003e(event: \u003ca href=\"#nativenavigationtransitionevent\"\u003eNativeNavigationTransitionEvent\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### addListener('transitionEnd', ...)\n\n```typescript\naddListener(eventName: 'transitionEnd', listenerFunc: (event: NativeNavigationTransitionEvent) =\u003e void) =\u003e Promise\u003cPluginListenerHandle\u003e\n```\n\n| Param | Type |\n| ------------------ | --------------------------------------------------------------------------------------------------------------- |\n| **`eventName`** | \u003ccode\u003e'transitionEnd'\u003c/code\u003e |\n| **`listenerFunc`** | \u003ccode\u003e(event: \u003ca href=\"#nativenavigationtransitionevent\"\u003eNativeNavigationTransitionEvent\u003c/a\u003e) =\u0026gt; void\u003c/code\u003e |\n\n**Returns:** \u003ccode\u003ePromise\u0026lt;\u003ca href=\"#pluginlistenerhandle\"\u003ePluginListenerHandle\u003c/a\u003e\u0026gt;\u003c/code\u003e\n\n--------------------\n\n\n### Interfaces\n\n\n#### NativeNavigationInsetsResult\n\nReturned by methods that may change safe content bounds.\n\n| Prop | Type |\n| ------------ | ------------------------------------------------------------------------- |\n| **`insets`** | \u003ccode\u003e\u003ca href=\"#nativenavigationinsets\"\u003eNativeNavigationInsets\u003c/a\u003e\u003c/code\u003e |\n\n\n#### NativeNavigationInsets\n\nInsets exposed to web content.\n\n| Prop | Type |\n| ------------------ | ------------------- |\n| **`top`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`right`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`bottom`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`left`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`navbarHeight`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`tabbarHeight`** | \u003ccode\u003enumber\u003c/code\u003e |\n\n\n#### NativeNavigationConfigureOptions\n\nGlobal plugin configuration.\n\n| Prop | Type | Description |\n| ----------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| **`enabled`** | \u003ccode\u003eboolean\u003c/code\u003e | Enables or disables the native chrome host. |\n| **`platformStyle`** | \u003ccode\u003e\u003ca href=\"#nativenavigationplatformstyle\"\u003eNativeNavigationPlatformStyle\u003c/a\u003e\u003c/code\u003e | Native style preference. `auto` uses the current platform. |\n| **`contentInsetMode`** | \u003ccode\u003e\u003ca href=\"#nativenavigationcontentinsetmode\"\u003eNativeNavigationContentInsetMode\u003c/a\u003e\u003c/code\u003e | When `css`, the plugin writes CSS variables on `document.documentElement`. |\n| **`animationDuration`** | \u003ccode\u003enumber\u003c/code\u003e | Default native transition duration in milliseconds. |\n| **`colors`** | \u003ccode\u003e\u003ca href=\"#nativenavigationcolors\"\u003eNativeNavigationColors\u003c/a\u003e\u003c/code\u003e | Shared color hints for native bars. |\n\n\n#### NativeNavigationColors\n\nNative bar colors. Use CSS-style hex strings (`#RRGGBB` or `#AARRGGBB`).\n\n| Prop | Type | Description |\n| --------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |\n| **`dynamic`** | \u003ccode\u003eboolean\u003c/code\u003e | When `true`, Android 12+ derives unspecified bar colors from Material You system palettes. Explicit color fields still win. |\n| **`tint`** | \u003ccode\u003estring\u003c/code\u003e | Tint color for active buttons/items. |\n| **`inactiveTint`** | \u003ccode\u003estring\u003c/code\u003e | Color for inactive tab items. |\n| **`background`** | \u003ccode\u003estring\u003c/code\u003e | Optional background tint. Ignored on iOS 26+ so UIKit can preserve the system Liquid Glass navigation appearance. |\n| **`foreground`** | \u003ccode\u003estring\u003c/code\u003e | Title and label text color where the native platform supports it. |\n| **`badgeBackground`** | \u003ccode\u003estring\u003c/code\u003e | Badge background color for native tab badges. |\n| **`badgeText`** | \u003ccode\u003estring\u003c/code\u003e | Badge text color for native tab badges. |\n| **`indicator`** | \u003ccode\u003estring\u003c/code\u003e | Active tab indicator color on Android. |\n| **`ripple`** | \u003ccode\u003estring\u003c/code\u003e | Tab press ripple color on Android. |\n\n\n#### NativeNavigationNavbarOptions\n\nNative navbar state.\n\n| Prop | Type | Description |\n| ----------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |\n| **`hidden`** | \u003ccode\u003eboolean\u003c/code\u003e | Hide the native navbar. |\n| **`title`** | \u003ccode\u003estring\u003c/code\u003e | Main title. |\n| **`subtitle`** | \u003ccode\u003estring\u003c/code\u003e | Secondary title where supported by the platform. |\n| **`large`** | \u003ccode\u003eboolean\u003c/code\u003e | Prefer a large iOS title style. |\n| **`transparent`** | \u003ccode\u003eboolean\u003c/code\u003e | Prefer transparent/scroll-edge style. |\n| **`blurEffect`** | \u003ccode\u003e\u003ca href=\"#nativenavigationblureffect\"\u003eNativeNavigationBlurEffect\u003c/a\u003e\u003c/code\u003e | iOS blur/material effect for the navbar background when glass is not available. Defaults to `systemChromeMaterial` for transparent bars. |\n| **`backButton`** | \u003ccode\u003e\u003ca href=\"#nativenavigationbackbutton\"\u003eNativeNavigationBackButton\u003c/a\u003e\u003c/code\u003e | Back button state. |\n| **`leftItems`** | \u003ccode\u003eNativeNavigationBarButton[]\u003c/code\u003e | Left-side action buttons. |\n| **`rightItems`** | \u003ccode\u003eNativeNavigationBarButton[]\u003c/code\u003e | Right-side action buttons. |\n| **`colors`** | \u003ccode\u003e\u003ca href=\"#nativenavigationcolors\"\u003eNativeNavigationColors\u003c/a\u003e\u003c/code\u003e | Navbar color hints. |\n| **`animated`** | \u003ccode\u003eboolean\u003c/code\u003e | Animate native navbar changes. |\n\n\n#### NativeNavigationBackButton\n\nNative back button configuration.\n\n| Prop | Type | Description |\n| ------------- | -------------------- | -------------------------------- |\n| **`visible`** | \u003ccode\u003eboolean\u003c/code\u003e | Show the native back affordance. |\n| **`title`** | \u003ccode\u003estring\u003c/code\u003e | Optional back title. |\n\n\n#### NativeNavigationBarButton\n\nA button shown in the native navbar.\n\n| Prop | Type | Description |\n| ------------- | --------------------------------------------------------------------- | -------------------------------------------------- |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e | Stable id returned in `navbarItemTap`. |\n| **`title`** | \u003ccode\u003estring\u003c/code\u003e | Visible text label. |\n| **`icon`** | \u003ccode\u003e\u003ca href=\"#nativenavigationicon\"\u003eNativeNavigationIcon\u003c/a\u003e\u003c/code\u003e | Native icon descriptor. |\n| **`enabled`** | \u003ccode\u003eboolean\u003c/code\u003e | Whether the action is enabled. Defaults to `true`. |\n\n\n#### NativeNavigationIcon\n\nA serializable icon descriptor. Framework nodes are intentionally not accepted\nbecause icons are rendered by native UI.\n\n| Prop | Type | Description |\n| -------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`src`** | \u003ccode\u003estring\u003c/code\u003e | Cross-platform asset path or URL fallback. |\n| **`svg`** | \u003ccode\u003estring\u003c/code\u003e | Cross-platform inline SVG markup. The native renderers support common icon shapes such as path, line, polyline, polygon, circle, and rect. SVG icons are rendered as template images by default so native tint colors still apply. |\n| **`width`** | \u003ccode\u003enumber\u003c/code\u003e | Preferred rendered icon width in native points/dp. Defaults to `24`. |\n| **`height`** | \u003ccode\u003enumber\u003c/code\u003e | Preferred rendered icon height in native points/dp. Defaults to `24`. |\n| **`template`** | \u003ccode\u003eboolean\u003c/code\u003e | When `true`, native tint colors are applied to the rendered SVG/image. Defaults to `true`. |\n| **`ios`** | \u003ccode\u003e{ sfSymbol?: string; image?: string; svg?: string; }\u003c/code\u003e | iOS-specific SF Symbol, bundled image name, or inline SVG. |\n| **`android`** | \u003ccode\u003e{ resource?: string; image?: string; svg?: string; }\u003c/code\u003e | Android-specific drawable resource, asset name, or inline SVG. |\n\n\n#### NativeNavigationTabbarOptions\n\nNative tabbar state.\n\n| Prop | Type | Description |\n| ------------------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`hidden`** | \u003ccode\u003eboolean\u003c/code\u003e | Hide the native tabbar. |\n| **`tabs`** | \u003ccode\u003eNativeNavigationTab[]\u003c/code\u003e | Tab definitions. |\n| **`selectedId`** | \u003ccode\u003estring\u003c/code\u003e | Currently selected tab id. |\n| **`labels`** | \u003ccode\u003eboolean\u003c/code\u003e | Show text labels. Defaults to `true`. |\n| **`labelVisibilityMode`** | \u003ccode\u003e\u003ca href=\"#nativenavigationtablabelvisibilitymode\"\u003eNativeNavigationTabLabelVisibilityMode\u003c/a\u003e\u003c/code\u003e | Native label visibility mode. Overrides `labels` when provided. |\n| **`icons`** | \u003ccode\u003eboolean\u003c/code\u003e | Show icons. Defaults to `true`. |\n| **`colors`** | \u003ccode\u003e\u003ca href=\"#nativenavigationcolors\"\u003eNativeNavigationColors\u003c/a\u003e\u003c/code\u003e | Tabbar color hints. |\n| **`blurEffect`** | \u003ccode\u003e\u003ca href=\"#nativenavigationblureffect\"\u003eNativeNavigationBlurEffect\u003c/a\u003e\u003c/code\u003e | iOS blur/material effect for the tabbar background when glass is not available. |\n| **`disableTransparentOnScrollEdge`** | \u003ccode\u003eboolean\u003c/code\u003e | Keep the iOS scroll-edge tabbar appearance from becoming transparent. Mirrors Expo Router native tabs' `disableTransparentOnScrollEdge` option. Defaults to `false`. |\n| **`disableIndicator`** | \u003ccode\u003eboolean\u003c/code\u003e | Disable the Android active tab indicator. |\n| **`indicatorColor`** | \u003ccode\u003estring\u003c/code\u003e | Active tab indicator color on Android. `colors.indicator` is also supported. |\n| **`rippleColor`** | \u003ccode\u003estring\u003c/code\u003e | Tab press ripple color on Android. `colors.ripple` is also supported. |\n| **`badgeBackgroundColor`** | \u003ccode\u003estring\u003c/code\u003e | Badge background color. `colors.badgeBackground` is also supported. |\n| **`badgeTextColor`** | \u003ccode\u003estring\u003c/code\u003e | Badge text color. `colors.badgeText` is also supported. |\n| **`animated`** | \u003ccode\u003eboolean\u003c/code\u003e | Animate native tabbar changes. |\n\n\n#### NativeNavigationTab\n\nA native tab item.\n\n| Prop | Type | Description |\n| ------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e | Stable tab id returned in `tabSelect`. |\n| **`title`** | \u003ccode\u003estring\u003c/code\u003e | Visible tab label. |\n| **`icon`** | \u003ccode\u003e\u003ca href=\"#nativenavigationicon\"\u003eNativeNavigationIcon\u003c/a\u003e\u003c/code\u003e | Native icon descriptor. |\n| **`selectedIcon`** | \u003ccode\u003e\u003ca href=\"#nativenavigationicon\"\u003eNativeNavigationIcon\u003c/a\u003e\u003c/code\u003e | Optional selected-state icon. |\n| **`badge`** | \u003ccode\u003estring \\| number\u003c/code\u003e | Optional badge. Numeric badges are supported on both platforms; text badge support depends on platform capabilities. |\n| **`enabled`** | \u003ccode\u003eboolean\u003c/code\u003e | Whether the tab is enabled. Defaults to `true`. |\n\n\n#### NativeNavigationTransitionResult\n\nNative transition result.\n\n| Prop | Type |\n| --------------- | --------------------------------------------------------------------------------------------------- |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e |\n| **`direction`** | \u003ccode\u003e\u003ca href=\"#nativenavigationtransitiondirection\"\u003eNativeNavigationTransitionDirection\u003c/a\u003e\u003c/code\u003e |\n| **`duration`** | \u003ccode\u003enumber\u003c/code\u003e |\n\n\n#### NativeNavigationBeginTransitionOptions\n\nBegin a native transition transaction before JS changes route content.\n\n| Prop | Type | Description |\n| ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e | |\n| **`direction`** | \u003ccode\u003e\u003ca href=\"#nativenavigationtransitiondirection\"\u003eNativeNavigationTransitionDirection\u003c/a\u003e\u003c/code\u003e | |\n| **`duration`** | \u003ccode\u003enumber\u003c/code\u003e | |\n| **`sourceRect`** | \u003ccode\u003e\u003ca href=\"#nativenavigationrect\"\u003eNativeNavigationRect\u003c/a\u003e\u003c/code\u003e | Source rectangle for `zoom` transitions. Use viewport coordinates such as those returned by `Element.getBoundingClientRect()`. |\n| **`targetRect`** | \u003ccode\u003e\u003ca href=\"#nativenavigationrect\"\u003eNativeNavigationRect\u003c/a\u003e\u003c/code\u003e | Destination rectangle for shared-element-style `zoom` transitions. |\n| **`cornerRadius`** | \u003ccode\u003enumber\u003c/code\u003e | Corner radius used while animating a `zoom` transition. |\n\n\n#### NativeNavigationRect\n\nA rectangle in WebView viewport coordinates, expressed in native points/dp.\n\n| Prop | Type |\n| ------------ | ------------------- |\n| **`x`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`y`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`width`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`height`** | \u003ccode\u003enumber\u003c/code\u003e |\n\n\n#### NativeNavigationFinishTransitionOptions\n\nFinish a native transition transaction after JS has changed route content.\n\n| Prop | Type | Description |\n| ------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e | |\n| **`direction`** | \u003ccode\u003e\u003ca href=\"#nativenavigationtransitiondirection\"\u003eNativeNavigationTransitionDirection\u003c/a\u003e\u003c/code\u003e | |\n| **`duration`** | \u003ccode\u003enumber\u003c/code\u003e | |\n| **`sourceRect`** | \u003ccode\u003e\u003ca href=\"#nativenavigationrect\"\u003eNativeNavigationRect\u003c/a\u003e\u003c/code\u003e | Source rectangle for `zoom` transitions when no active source was recorded. |\n| **`targetRect`** | \u003ccode\u003e\u003ca href=\"#nativenavigationrect\"\u003eNativeNavigationRect\u003c/a\u003e\u003c/code\u003e | Destination rectangle for shared-element-style `zoom` transitions. |\n| **`cornerRadius`** | \u003ccode\u003enumber\u003c/code\u003e | Corner radius used while animating a `zoom` transition. |\n\n\n#### PluginVersionResult\n\nPlugin version payload.\n\n| Prop | Type | Description |\n| ------------- | ------------------- | ----------------------------------------------------------- |\n| **`version`** | \u003ccode\u003estring\u003c/code\u003e | Version identifier returned by the platform implementation. |\n\n\n#### PluginListenerHandle\n\n| Prop | Type |\n| ------------ | ----------------------------------------- |\n| **`remove`** | \u003ccode\u003e() =\u0026gt; Promise\u0026lt;void\u0026gt;\u003c/code\u003e |\n\n\n#### NativeNavigationBackEvent\n\n| Prop | Type |\n| ------------ | --------------------- |\n| **`source`** | \u003ccode\u003e'navbar'\u003c/code\u003e |\n\n\n#### NativeNavigationBarItemTapEvent\n\n| Prop | Type |\n| --------------- | ------------------------------ |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e |\n| **`title`** | \u003ccode\u003estring\u003c/code\u003e |\n| **`placement`** | \u003ccode\u003e'left' \\| 'right'\u003c/code\u003e |\n\n\n#### NativeNavigationTabSelectEvent\n\n| Prop | Type |\n| ----------- | ------------------- |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e |\n| **`index`** | \u003ccode\u003enumber\u003c/code\u003e |\n| **`title`** | \u003ccode\u003estring\u003c/code\u003e |\n\n\n#### NativeNavigationSafeAreaChangedEvent\n\n| Prop | Type |\n| ------------ | ------------------------------------------------------------------------- |\n| **`insets`** | \u003ccode\u003e\u003ca href=\"#nativenavigationinsets\"\u003eNativeNavigationInsets\u003c/a\u003e\u003c/code\u003e |\n\n\n#### NativeNavigationTransitionEvent\n\n| Prop | Type |\n| --------------- | --------------------------------------------------------------------------------------------------- |\n| **`id`** | \u003ccode\u003estring\u003c/code\u003e |\n| **`direction`** | \u003ccode\u003e\u003ca href=\"#nativenavigationtransitiondirection\"\u003eNativeNavigationTransitionDirection\u003c/a\u003e\u003c/code\u003e |\n| **`duration`** | \u003ccode\u003enumber\u003c/code\u003e |\n\n\n### Type Aliases\n\n\n#### NativeNavigationPlatformStyle\n\nPlatform rendering preference for the native bars.\n\n\u003ccode\u003e'auto' | 'ios' | 'android'\u003c/code\u003e\n\n\n#### NativeNavigationContentInsetMode\n\nHow the plugin exposes native bar sizes to web content.\n\n\u003ccode\u003e'css' | 'none'\u003c/code\u003e\n\n\n#### NativeNavigationBlurEffect\n\nNative material/blur effect preference.\n\n\u003ccode\u003e'none' | 'systemDefault' | 'extraLight' | 'light' | 'dark' | 'regular' | 'prominent' | 'systemUltraThinMaterial' | 'systemThinMaterial' | 'systemMaterial' | 'systemThickMaterial' | 'systemChromeMaterial' | 'systemUltraThinMaterialLight' | 'systemThinMaterialLight' | 'systemMaterialLight' | 'systemThickMaterialLight' | 'systemChromeMaterialLight' | 'systemUltraThinMaterialDark' | 'systemThinMaterialDark' | 'systemMaterialDark' | 'systemThickMaterialDark' | 'systemChromeMaterialDark'\u003c/code\u003e\n\n\n#### NativeNavigationTabLabelVisibilityMode\n\nNative tab label visibility behavior.\n\n\u003ccode\u003e'auto' | 'selected' | 'labeled' | 'unlabeled'\u003c/code\u003e\n\n\n#### NativeNavigationTransitionDirection\n\nNavigation animation direction.\n\n\u003ccode\u003e'forward' | 'back' | 'root' | 'tab' | 'zoom' | 'none'\u003c/code\u003e\n\n\u003c/docgen-api\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-go%2Fcapacitor-native-navigation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcap-go%2Fcapacitor-native-navigation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcap-go%2Fcapacitor-native-navigation/lists"}