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

ShaneK · web-flow · commit 66a3e8ab3bb7 · 2026-04-13T11:19:45.000-07:00
Issue number: resolves internal

---------

## What is the current behavior?
The swipe-to-go-back gesture on ion-router-outlet is controlled
differently across frameworks:

- React and Vue check the `swipeBackEnabled` config option on every
swipe attempt in their framework wrappers (`StackManager.canStart()` and
`IonRouterOutlet.canStart()`)
- Angular reads the config once at mount and controls the gesture
through its directive's `swipeGesture` setter
- There is no public, per-outlet property to enable or disable the
gesture. The only mechanism is the global `swipeBackEnabled` config
option

## What is the new behavior?
`ion-router-outlet` now exposes a public `swipeGesture` property in core
that controls the swipe-to-go-back gesture per outlet instance. It
defaults to true in "ios" mode and false in "md" mode, matching existing
behavior.

- The `swipeBackEnabled` config is read once when the outlet mounts (as
the default for `swipeGesture`) rather than checked on every swipe
attempt
- The config check has been removed from React's StackManager and Vue's
IonRouterOutlet -- core now owns this state
- Angular's directive forwards the value to the core component's
`swipeGesture` property for consistency
- Apps can disable the gesture on a specific outlet: `&lt;IonRouterOutlet
swipeGesture={false} /&gt;`
- Apps that set `swipeBackEnabled` once at startup require no changes

## Does this introduce a breaking change?

- [X] Yes
- [ ] No

## Other information

I tried to align the updates to the BREAKING.md documents with the RR6
PR's changes to it to prevent issues from merging as much as possible
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/standalone/swipe-gesture-disabled.spec.ts b/packages/angular/test/base/e2e/src/standalone/swipe-gesture-disabled.spec.ts
@@ -0,0 +1,22 @@
+import { test } from '@playwright/test';
+import { ionSwipeToGoBack } from '../../utils/drag-utils';
+import { ionPageVisible, ionPageHidden } from '../../utils/test-utils';
+
+test.describe('Swipe Gesture Disabled', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/standalone/swipe-gesture-disabled?ionic:mode=ios');
+  });
+
+  test('should not swipe back when swipeGesture is false', async ({ page }) => {
+    await ionPageVisible(page, 'app-swipe-gesture-disabled-main');
+
+    await page.locator('#swipe-disabled-details').click();
+    await ionPageVisible(page, 'app-swipe-gesture-disabled-details');
+    await ionPageHidden(page, 'app-swipe-gesture-disabled-main');
+
+    await ionSwipeToGoBack(page, true);
+
+    await ionPageVisible(page, 'app-swipe-gesture-disabled-details');
+    await ionPageHidden(page, 'app-swipe-gesture-disabled-main');
+  });
+});
diff --git a/packages/angular/test/base/src/app/standalone/app-standalone/app.routes.ts b/packages/angular/test/base/src/app/standalone/app-standalone/app.routes.ts
@@ -55,6 +55,14 @@ export const routes: Routes = [
         ]
       },
       { path: 'tabs-basic', loadComponent: () => import('../tabs-basic/tabs-basic.component').then(c => c.TabsBasicComponent) },
+      {
+        path: 'swipe-gesture-disabled',
+        loadComponent: () => import('../swipe-gesture-disabled/swipe-gesture-disabled.component').then(c => c.SwipeGestureDisabledComponent),
+        children: [
+          { path: '', loadComponent: () => import('../swipe-gesture-disabled/swipe-gesture-disabled-main.component').then(c => c.SwipeGestureDisabledMainComponent) },
+          { path: 'details', loadComponent: () => import('../swipe-gesture-disabled/swipe-gesture-disabled-details.component').then(c => c.SwipeGestureDisabledDetailsComponent) }
+        ]
+      },
       {
         path: 'validation',
         children: [
diff --git a/packages/angular/test/base/src/app/standalone/home-page/home-page.component.html b/packages/angular/test/base/src/app/standalone/home-page/home-page.component.html
@@ -79,6 +79,11 @@
         Tabs Basic Test
       </ion-label>
     </ion-item>
+    <ion-item routerLink="/standalone/swipe-gesture-disabled">
+      <ion-label>
+        Swipe Gesture Disabled Test
+      </ion-label>
+    </ion-item>
   </ion-list>
 
   <ion-list>
diff --git a/packages/angular/test/base/src/app/standalone/swipe-gesture-disabled/swipe-gesture-disabled-details.component.ts b/packages/angular/test/base/src/app/standalone/swipe-gesture-disabled/swipe-gesture-disabled-details.component.ts
@@ -0,0 +1,22 @@
+import { Component } from '@angular/core';
+import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-swipe-gesture-disabled-details',
+  template: `
+    <ion-header>
+      <ion-toolbar>
+        <ion-buttons slot="start">
+          <ion-back-button defaultHref="/standalone/swipe-gesture-disabled"></ion-back-button>
+        </ion-buttons>
+        <ion-title>Details</ion-title>
+      </ion-toolbar>
+    </ion-header>
+    <ion-content>
+      <div>Details (swipe disabled)</div>
+    </ion-content>
+  `,
+  standalone: true,
+  imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar]
+})
+export class SwipeGestureDisabledDetailsComponent {}
diff --git a/packages/angular/test/base/src/app/standalone/swipe-gesture-disabled/swipe-gesture-disabled-main.component.ts b/packages/angular/test/base/src/app/standalone/swipe-gesture-disabled/swipe-gesture-disabled-main.component.ts
@@ -0,0 +1,17 @@
+import { Component } from '@angular/core';
+import { RouterModule } from '@angular/router';
+import { IonContent, IonItem, IonLabel, IonRouterLink } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-swipe-gesture-disabled-main',
+  template: `
+    <ion-content>
+      <ion-item routerLink="/standalone/swipe-gesture-disabled/details" id="swipe-disabled-details">
+        <ion-label>Details</ion-label>
+      </ion-item>
+    </ion-content>
+  `,
+  standalone: true,
+  imports: [IonContent, IonItem, IonLabel, IonRouterLink, RouterModule]
+})
+export class SwipeGestureDisabledMainComponent {}
diff --git a/packages/angular/test/base/src/app/standalone/swipe-gesture-disabled/swipe-gesture-disabled.component.ts b/packages/angular/test/base/src/app/standalone/swipe-gesture-disabled/swipe-gesture-disabled.component.ts
@@ -0,0 +1,22 @@
+import { Component } from '@angular/core';
+import { IonBackButton, IonButtons, IonContent, IonHeader, IonRouterOutlet, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-swipe-gesture-disabled',
+  template: `
+    <ion-header>
+      <ion-toolbar>
+        <ion-buttons slot="start">
+          <ion-back-button defaultHref="/standalone"></ion-back-button>
+        </ion-buttons>
+        <ion-title>Swipe Gesture Disabled</ion-title>
+      </ion-toolbar>
+    </ion-header>
+    <ion-content>
+      <ion-router-outlet [swipeGesture]="false"></ion-router-outlet>
+    </ion-content>
+  `,
+  standalone: true,
+  imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonRouterOutlet, IonTitle, IonToolbar]
+})
+export class SwipeGestureDisabledComponent {}
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
diff --git a/packages/vue/test/base/src/views/Home.vue b/packages/vue/test/base/src/views/Home.vue
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
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(`