feat(router-outlet): add swipeGesture prop to control swipe-to-go-back per outlet

ShaneK · ShaneK · commit f1d9d2228550 · 2026-04-01T09:27:15.000-07:00
diff --git a/BREAKING.md b/BREAKING.md
diff --git a/BREAKING_ARCHIVE/v8.md b/BREAKING_ARCHIVE/v8.md
diff --git a/core/api.txt b/core/api.txt
@@ -1589,6 +1589,7 @@ ion-router-outlet,shadow
 ion-router-outlet,prop,animated,boolean,true,false,false
 ion-router-outlet,prop,animation,((baseEl: any, opts?: any) => Animation) | undefined,undefined,false,false
 ion-router-outlet,prop,mode,"ios" | "md",getIonMode(this),false,false
+ion-router-outlet,prop,swipeGesture,boolean | undefined,undefined,false,false
 
 ion-row,shadow
 
diff --git a/core/src/components.d.ts b/core/src/components.d.ts
@@ -2915,6 +2915,10 @@ export namespace Components {
          */
         "mode": "ios" | "md";
         "setRouteId": (id: string, params: ComponentProps | undefined, direction: RouterDirection, animation?: AnimationBuilder) => Promise<RouteWrite>;
+        /**
+          * If `true`, the router-outlet should allow navigation via swipe-to-go-back gesture. Defaults to `true` for `"ios"` mode and `false` for `"md"` mode.
+         */
+        "swipeGesture"?: boolean;
         "swipeHandler"?: SwipeGestureHandler;
     }
     interface IonRow {
@@ -8229,6 +8233,10 @@ declare namespace LocalJSX {
         "onIonNavDidChange"?: (event: IonRouterOutletCustomEvent<void>) => void;
         "onIonNavWillChange"?: (event: IonRouterOutletCustomEvent<void>) => void;
         "onIonNavWillLoad"?: (event: IonRouterOutletCustomEvent<void>) => void;
+        /**
+          * If `true`, the router-outlet should allow navigation via swipe-to-go-back gesture. Defaults to `true` for `"ios"` mode and `false` for `"md"` mode.
+         */
+        "swipeGesture"?: boolean;
         "swipeHandler"?: SwipeGestureHandler;
     }
     interface IonRow {
@@ -9723,6 +9731,7 @@ declare namespace LocalJSX {
     interface IonRouterOutletAttributes {
         "mode": "ios" | "md";
         "animated": boolean;
+        "swipeGesture": boolean;
     }
     interface IonSearchbarAttributes {
         "color": Color;
diff --git a/core/src/components/router-outlet/router-outlet.tsx b/core/src/components/router-outlet/router-outlet.tsx
@@ -53,13 +53,21 @@ export class RouterOutlet implements ComponentInterface, NavOutlet {
   /** This property allows to create custom transition using AnimationBuilder functions. */
   @Prop() animation?: AnimationBuilder;
 
+  /**
+   * If `true`, the router-outlet should allow navigation via swipe-to-go-back gesture.
+   * Defaults to `true` for `"ios"` mode and `false` for `"md"` mode.
+   */
+  @Prop({ mutable: true }) swipeGesture?: boolean;
+  @Watch('swipeGesture')
+  swipeGestureChanged() {
+    this.updateGestureEnabled();
+  }
+
   /** @internal */
   @Prop() swipeHandler?: SwipeGestureHandler;
   @Watch('swipeHandler')
   swipeHandlerChanged() {
-    if (this.gesture) {
-      this.gesture.enable(this.swipeHandler !== undefined);
-    }
+    this.updateGestureEnabled();
   }
 
   /** @internal */
@@ -121,13 +129,24 @@ export class RouterOutlet implements ComponentInterface, NavOutlet {
         }
       }
     );
-    this.swipeHandlerChanged();
+
+    if (this.swipeGesture === undefined) {
+      this.swipeGesture = config.getBoolean('swipeBackEnabled', this.mode === 'ios');
+    } else {
+      this.updateGestureEnabled();
+    }
   }
 
   componentWillLoad() {
     this.ionNavWillLoad.emit();
   }
 
+  private updateGestureEnabled() {
+    if (this.gesture) {
+      this.gesture.enable(this.swipeHandler !== undefined && this.swipeGesture === true);
+    }
+  }
+
   disconnectedCallback() {
     if (this.gesture) {
       this.gesture.destroy();
diff --git a/packages/angular/common/src/directives/navigation/router-outlet.ts b/packages/angular/common/src/directives/navigation/router-outlet.ts
@@ -108,6 +108,8 @@ export abstract class IonRouterOutlet implements OnDestroy, OnInit {
           onEnd: (shouldContinue) => this.stackCtrl.endBackTransition(shouldContinue),
         }
       : undefined;
+
+    this.nativeEl.swipeGesture = swipe;
   }
 
   constructor(
diff --git a/packages/angular/test/base/e2e/src/lazy/routing.spec.ts b/packages/angular/test/base/e2e/src/lazy/routing.spec.ts
@@ -19,6 +19,22 @@ test.describe('Routing', () => {
     await expect(page.locator('app-router-link-page')).toHaveAttribute('class', 'ion-page can-go-back');
   });
 
+  test('should not swipe back when swipeGesture is false', async ({ page }) => {
+    await page.locator('#routerLink').click();
+
+    await ionPageHidden(page, 'app-router-link');
+    await ionPageVisible(page, 'app-router-link-page');
+
+    await page.locator('ion-router-outlet').evaluate((el: any) => {
+      el.swipeGesture = false;
+    });
+
+    await ionSwipeToGoBack(page, true);
+
+    await ionPageVisible(page, 'app-router-link-page');
+    await ionPageHidden(page, 'app-router-link');
+  });
+
   test('should swipe and go back', async ({ page }) => {
     await page.locator('#routerLink').click();
 
diff --git a/packages/react-router/src/ReactRouter/StackManager.tsx b/packages/react-router/src/ReactRouter/StackManager.tsx
@@ -1,5 +1,5 @@
 import type { RouteInfo, StackContextState, ViewItem } from '@ionic/react';
-import { RouteManagerContext, StackContext, generateId, getConfig } from '@ionic/react';
+import { RouteManagerContext, StackContext, generateId } from '@ionic/react';
 import React from 'react';
 
 import { clonePageElement } from './clonePageElement';
@@ -211,12 +211,6 @@ export class StackManager extends React.PureComponent<StackManagerProps, StackMa
 
   async setupRouterOutlet(routerOutlet: HTMLIonRouterOutletElement) {
     const canStart = () => {
-      const config = getConfig();
-      const swipeEnabled = config && config.get('swipeBackEnabled', routerOutlet.mode === 'ios');
-      if (!swipeEnabled) {
-        return false;
-      }
-
       const { routeInfo } = this.props;
 
       const propsToUse =
diff --git a/packages/react-router/test/base/src/App.tsx b/packages/react-router/test/base/src/App.tsx
@@ -31,7 +31,7 @@ import NestedOutlet2 from './pages/nested-outlet/NestedOutlet2';
 import ReplaceAction from './pages/replace-action/Replace';
 import TabsContext from './pages/tab-context/TabContext';
 import { OutletRef } from './pages/outlet-ref/OutletRef';
-import { SwipeToGoBack } from './pages/swipe-to-go-back/SwipToGoBack';
+import { SwipeToGoBack, SwipeToGoBackDisabled } from './pages/swipe-to-go-back/SwipToGoBack';
 import Refs from './pages/refs/Refs';
 import DynamicIonpageClassnames from './pages/dynamic-ionpage-classnames/DynamicIonpageClassnames';
 import Tabs from './pages/tabs/Tabs';
@@ -57,6 +57,7 @@ const App: React.FC = () => {
           <Route path="/tab-context" component={TabsContext} />
           <Route path="/outlet-ref" component={OutletRef} />
           <Route path="/swipe-to-go-back" component={SwipeToGoBack} />
+          <Route path="/swipe-to-go-back-disabled" component={SwipeToGoBackDisabled} />
           <Route path="/dynamic-ionpage-classnames" component={DynamicIonpageClassnames} />
           <Route path="/tabs" component={Tabs} />
           <Route path="/tabs-secondary" component={TabsSecondary} />
diff --git a/packages/react-router/test/base/src/pages/Main.tsx b/packages/react-router/test/base/src/pages/Main.tsx
@@ -52,6 +52,9 @@ const Main: React.FC<MainProps> = () => {
           <IonItem routerLink="/swipe-to-go-back">
             <IonLabel>Swipe to go back</IonLabel>
           </IonItem>
+          <IonItem routerLink="/swipe-to-go-back-disabled">
+            <IonLabel>Swipe to go back (disabled)</IonLabel>
+          </IonItem>
           <IonItem routerLink="/dynamic-ionpage-classnames">
             <IonLabel>Dynamic IonPage Classnames</IonLabel>
           </IonItem>
diff --git a/packages/react-router/test/base/src/pages/swipe-to-go-back/SwipToGoBack.tsx b/packages/react-router/test/base/src/pages/swipe-to-go-back/SwipToGoBack.tsx
@@ -38,6 +38,48 @@ const Main: React.FC = () => {
   );
 };
 
+export const SwipeToGoBackDisabled: React.FC = () => {
+  return (
+    <IonRouterOutlet id="swipe-to-go-back-disabled" swipeGesture={false}>
+      <Route path="/swipe-to-go-back-disabled" component={DisabledMain} exact />
+      <Route path="/swipe-to-go-back-disabled/details" component={DisabledDetails} />
+    </IonRouterOutlet>
+  );
+};
+
+const DisabledMain: React.FC = () => {
+  return (
+    <IonPage data-pageid="disabled-main">
+      <IonHeader>
+        <IonToolbar>
+          <IonTitle>Disabled Main</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent>
+        <IonItem routerLink="/swipe-to-go-back-disabled/details">Details</IonItem>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+const DisabledDetails: React.FC = () => {
+  return (
+    <IonPage data-pageid="disabled-details">
+      <IonHeader>
+        <IonToolbar>
+          <IonButtons>
+            <IonBackButton></IonBackButton>
+          </IonButtons>
+          <IonTitle>Disabled Details</IonTitle>
+        </IonToolbar>
+      </IonHeader>
+      <IonContent>
+        <div>Details (swipe disabled)</div>
+      </IonContent>
+    </IonPage>
+  );
+};
+
 const Details: React.FC = () => {
   return (
     <IonPage data-pageid="details">
diff --git a/packages/react-router/test/base/tests/e2e/specs/swipe-to-go-back.cy.js b/packages/react-router/test/base/tests/e2e/specs/swipe-to-go-back.cy.js
@@ -141,4 +141,17 @@ describe('Swipe To Go Back', () => {
 
     cy.ionPageVisible('params-1');
   })
+
+  it('should not swipe back when swipeGesture is false', () => {
+    cy.visit(`http://localhost:${port}/swipe-to-go-back-disabled?${IOS_MODE}`);
+    cy.ionPageVisible('disabled-main');
+
+    cy.ionNav('ion-item', 'Details');
+    cy.ionPageVisible('disabled-details');
+    cy.ionPageHidden('disabled-main');
+
+    cy.ionSwipeToGoBack(true, 'ion-router-outlet#swipe-to-go-back-disabled');
+    cy.ionPageVisible('disabled-details');
+    cy.ionPageHidden('disabled-main');
+  });
 });
diff --git a/packages/vue/src/components/IonRouterOutlet.ts b/packages/vue/src/components/IonRouterOutlet.ts
@@ -20,7 +20,7 @@ import {
 import type { InjectionKey, Ref } from "vue";
 import { matchedRouteKey, routeLocationKey, useRoute } from "vue-router";
 
-import { fireLifecycle, generateId, getConfig } from "../utils";
+import { fireLifecycle, generateId } from "../utils";
 
 // TODO(FW-2969): types
 
@@ -34,6 +34,12 @@ const isViewVisible = (enteringEl: HTMLElement) => {
 const viewDepthKey: InjectionKey<0> = Symbol(0);
 export const IonRouterOutlet = /*@__PURE__*/ defineComponent({
   name: "IonRouterOutlet",
+  props: {
+    swipeGesture: {
+      type: Boolean,
+      default: undefined,
+    },
+  },
   setup() {
     defineCustomElement();
 
@@ -127,12 +133,6 @@ export const IonRouterOutlet = /*@__PURE__*/ defineComponent({
     );
 
     const canStart = () => {
-      const config = getConfig();
-      const swipeEnabled =
-        config &&
-        config.get("swipeBackEnabled", ionRouterOutlet.value.mode === "ios");
-      if (!swipeEnabled) return false;
-
       const stack = viewStacks.getViewStack(id);
       if (!stack || stack.length <= 1) return false;
 
@@ -547,9 +547,18 @@ See https://ionicframework.com/docs/vue/navigation#ionpage for more information.
   render() {
     const { components, registerIonPage, injectedRoute } = this;
 
+    /**
+     * Forward props selectively to avoid setting undefined values
+     * that would override the web component's config-based defaults.
+     */
+    const routerOutletProps: Record<string, any> = { ref: "ionRouterOutlet" };
+    if (this.$props.swipeGesture !== undefined) {
+      routerOutletProps.swipeGesture = this.$props.swipeGesture;
+    }
+
     return h(
       "ion-router-outlet",
-      { ref: "ionRouterOutlet" },
+      routerOutletProps,
       components &&
         components.map((c: any) => {
           let props = {
diff --git a/packages/vue/test/base/src/router/index.ts b/packages/vue/test/base/src/router/index.ts
@@ -86,6 +86,20 @@ const routes: Array<RouteRecordRaw> = [
     path: '/reorder-group',
     component: () => import('@/views/ReorderGroup.vue')
   },
+  {
+    path: '/swipe-gesture-disabled',
+    component: () => import('@/views/swipe-gesture-disabled/SwipeGestureDisabledOutlet.vue'),
+    children: [
+      {
+        path: '',
+        component: () => import('@/views/swipe-gesture-disabled/SwipeGestureDisabledMain.vue')
+      },
+      {
+        path: 'details',
+        component: () => import('@/views/swipe-gesture-disabled/SwipeGestureDisabledDetails.vue')
+      }
+    ]
+  },
   {
     path: '/nested',
     component: () => import('@/views/nested/RouterOutlet.vue'),
diff --git a/packages/vue/test/base/src/views/Home.vue b/packages/vue/test/base/src/views/Home.vue
@@ -41,6 +41,9 @@
         <ion-item router-link="/nested" id="nested">
           <ion-label>Nested Router Outlet</ion-label>
         </ion-item>
+        <ion-item router-link="/swipe-gesture-disabled" id="swipe-gesture-disabled">
+          <ion-label>Swipe Gesture Disabled</ion-label>
+        </ion-item>
         <ion-item router-link="/tabs" id="tabs">
           <ion-label>Tabs</ion-label>
         </ion-item>
diff --git a/packages/vue/test/base/src/views/swipe-gesture-disabled/SwipeGestureDisabledDetails.vue b/packages/vue/test/base/src/views/swipe-gesture-disabled/SwipeGestureDisabledDetails.vue
@@ -0,0 +1,40 @@
+<template>
+  <ion-page data-pageid="swipe-gesture-disabled-details">
+    <ion-header>
+      <ion-toolbar>
+        <ion-buttons slot="start">
+          <ion-back-button default-href="/swipe-gesture-disabled"></ion-back-button>
+        </ion-buttons>
+        <ion-title>Swipe Disabled Details</ion-title>
+      </ion-toolbar>
+    </ion-header>
+    <ion-content>
+      <div>Details (swipe disabled)</div>
+    </ion-content>
+  </ion-page>
+</template>
+
+<script lang="ts">
+import {
+  IonBackButton,
+  IonButtons,
+  IonContent,
+  IonHeader,
+  IonPage,
+  IonTitle,
+  IonToolbar
+} from '@ionic/vue';
+import { defineComponent } from 'vue';
+
+export default defineComponent({
+  components: {
+    IonBackButton,
+    IonButtons,
+    IonContent,
+    IonHeader,
+    IonPage,
+    IonTitle,
+    IonToolbar
+  }
+});
+</script>
diff --git a/packages/vue/test/base/src/views/swipe-gesture-disabled/SwipeGestureDisabledMain.vue b/packages/vue/test/base/src/views/swipe-gesture-disabled/SwipeGestureDisabledMain.vue
diff --git a/packages/vue/test/base/src/views/swipe-gesture-disabled/SwipeGestureDisabledOutlet.vue b/packages/vue/test/base/src/views/swipe-gesture-disabled/SwipeGestureDisabledOutlet.vue
diff --git a/packages/vue/test/base/tests/e2e/specs/routing.cy.js b/packages/vue/test/base/tests/e2e/specs/routing.cy.js

Original file line number	Diff line number	Diff line change
`@@ -108,6 +108,8 @@ export abstract class IonRouterOutlet implements OnDestroy, OnInit {`
`108`	`108`	`onEnd: (shouldContinue) => this.stackCtrl.endBackTransition(shouldContinue),`
`109`	`109`	`}`
`110`	`110`	`: undefined;`
	`111`	`+`
	`112`	`+ this.nativeEl.swipeGesture = swipe;`
`111`	`113`	`}`
`112`	`114`
`113`	`115`	`constructor(`