# ion-back-button

URL: https://ionicframework.com/docs/api/back-button

**Encapsulation**: [shadow](/docs/reference/glossary.md#shadow)

The back button navigates back in the app's history when clicked. It is only displayed when there is history in the navigation stack, unless [`defaultHref`](#default-back-history) is set. The back button displays different text and icon based on the mode, but this can be customized.

## Basic Usage

**JavaScript**

```html
<ion-app>
  <ion-nav root="page-one"></ion-nav>
</ion-app>

<script>
  class PageOne extends HTMLElement {
    connectedCallback() {
      this.innerHTML = `
      <ion-header>
        <ion-toolbar>
          <ion-title>Back Button</ion-title>
        </ion-toolbar>
      </ion-header>
      <ion-content class="ion-padding">
        <h1>Page One</h1>
        <p>Navigate to the next page to see the back button.</p>
        <ion-nav-link router-direction="forward" component="page-two">
          <ion-button>Navigate</ion-button>
        </ion-nav-link>
      </ion-content>
    `;
    }
  }

  class PageTwo extends HTMLElement {
    connectedCallback() {
      this.innerHTML = `
      <ion-header>
        <ion-toolbar>
          <ion-buttons slot="start">
            <ion-back-button></ion-back-button>
          </ion-buttons>
          <ion-title>Back Button</ion-title>
        </ion-toolbar>
      </ion-header>
      <ion-content class="ion-padding">
        <h1>Page Two</h1>
        <p>Use the back button to navigate to the previous page.</p>
      </ion-content>
    `;
    }
  }

  customElements.define('page-one', PageOne);
  customElements.define('page-two', PageTwo);
</script>
```

**Angular**

`src/app/example.component.html`

```html
<ion-nav [root]="component"></ion-nav>
```

`src/app/example.component.ts`

```ts
import { Component } from '@angular/core';
import { IonNav } from '@ionic/angular';

import { PageOneComponent } from './page-one.component';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonNav],
})
export class ExampleComponent {
  component = PageOneComponent;
}
```

`src/app/page-one.component.ts`

```ts
import { Component } from '@angular/core';
import { IonButton, IonContent, IonHeader, IonNavLink, IonTitle, IonToolbar } from '@ionic/angular';

import { PageTwoComponent } from './page-two.component';

@Component({
  selector: 'app-page-one',
  template: `
    <ion-header>
      <ion-toolbar>
        <ion-title>Back Button</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">
      <h1>Page One</h1>
      <p>Navigate to the next page to see the back button.</p>
      <ion-nav-link router-direction="forward" [component]="component">
        <ion-button>Navigate</ion-button>
      </ion-nav-link>
    </ion-content>
  `,
  imports: [IonButton, IonContent, IonHeader, IonNavLink, IonTitle, IonToolbar],
})
export class PageOneComponent {
  component = PageTwoComponent;
}
```

`src/app/page-two.component.ts`

```ts
import { Component } from '@angular/core';
import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular';

@Component({
  selector: 'app-page-two',
  template: `
    <ion-header>
      <ion-toolbar>
        <ion-buttons slot="start">
          <ion-back-button></ion-back-button>
        </ion-buttons>
        <ion-title>Back Button</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">
      <h1>Page Two</h1>
      <p>Use the back button to navigate to the previous page.</p>
    </ion-content>
  `,
  imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar],
})
export class PageTwoComponent {}
```

**React**

`src/main.tsx`

```tsx
import React from 'react';
import { IonNav } from '@ionic/react';

import PageOne from './page-one';

function Example() {
  return <IonNav root={() => <PageOne />}></IonNav>;
}
export default Example;
```

`src/page-one.tsx`

```tsx
import React from 'react';
import { IonButton, IonHeader, IonContent, IonNavLink, IonToolbar, IonTitle } from '@ionic/react';

import PageTwo from './page-two';

function PageOne() {
  return (
    <>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Back Button</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent className="ion-padding">
        <h1>Page One</h1>
        <p>Navigate to the next page to see the back button.</p>
        <IonNavLink routerDirection="forward" component={() => <PageTwo />}>
          <IonButton>Navigate</IonButton>
        </IonNavLink>
      </IonContent>
    </>
  );
}

export default PageOne;
```

`src/page-two.tsx`

```tsx
import React from 'react';
import { IonBackButton, IonButtons, IonHeader, IonContent, IonToolbar, IonTitle } from '@ionic/react';

function PageTwo() {
  return (
    <>
      <IonHeader>
        <IonToolbar>
          <IonButtons slot="start">
            <IonBackButton></IonBackButton>
          </IonButtons>
          <IonTitle>Back Button</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent className="ion-padding">
        <h1>Page Two</h1>
        <p>Use the back button to navigate to the previous page.</p>
      </IonContent>
    </>
  );
}

export default PageTwo;
```

**Vue**

`src/components/Example.vue`

```html
<template>
  <ion-nav :root="component"></ion-nav>
</template>

<script setup lang="ts">
  import { IonNav } from '@ionic/vue';
  import PageOne from './PageOne.vue';

  const component = PageOne;
</script>
```

`src/components/PageOne.vue`

```html
<template>
  <ion-header>
    <ion-toolbar>
      <ion-title>Back Button</ion-title>
    </ion-toolbar>
  </ion-header>
  <ion-content class="ion-padding">
    <h1>Page One</h1>
    <p>Navigate to the next page to see the back button.</p>
    <ion-nav-link router-direction="forward" :component="component">
      <ion-button>Navigate</ion-button>
    </ion-nav-link>
  </ion-content>
</template>

<script setup lang="ts">
  import { IonButton, IonContent, IonHeader, IonNavLink, IonPage, IonTitle, IonToolbar } from '@ionic/vue';
  import PageTwo from './PageTwo.vue';

  const component = PageTwo;
</script>
```

`src/components/PageTwo.vue`

```html
<template>
  <ion-header>
    <ion-toolbar>
      <ion-buttons slot="start">
        <ion-back-button></ion-back-button>
      </ion-buttons>
      <ion-title>Back Button</ion-title>
    </ion-toolbar>
  </ion-header>
  <ion-content class="ion-padding">
    <h1>Page Two</h1>
    <p>Use the back button to navigate to the previous page.</p>
  </ion-content>
</template>

<script setup lang="ts">
  import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/vue';
</script>
```

## Custom Back Button

By default, the back button will display the text `"Back"` with a `"chevron-back"` icon on `ios`, and an `"arrow-back-sharp"` icon on `md`. This can be customized per back button component by setting the `icon` or `text` properties. Alternatively, it can be set globally using the `backButtonIcon` or `backButtonText` properties in the global config. Refer to the [Config docs](/docs/developing/config.md) for more information.

**JavaScript**

```html
<ion-app>
  <ion-nav root="page-one"></ion-nav>
</ion-app>

<script>
  class PageOne extends HTMLElement {
    connectedCallback() {
      this.innerHTML = `
      <ion-header>
        <ion-toolbar>
          <ion-title>Back Button</ion-title>
        </ion-toolbar>
      </ion-header>
      <ion-content class="ion-padding">
        <h1>Page One</h1>
        <p>Navigate to the next page to see the back button.</p>
        <ion-nav-link router-direction="forward" component="page-two">
          <ion-button>Navigate</ion-button>
        </ion-nav-link>
      </ion-content>
    `;
    }
  }

  class PageTwo extends HTMLElement {
    connectedCallback() {
      this.innerHTML = `
      <ion-header>
        <ion-toolbar>
          <ion-buttons slot="start">
            <ion-back-button text="Previous" icon="caret-back"></ion-back-button>
          </ion-buttons>
          <ion-title>Back Button</ion-title>
        </ion-toolbar>
      </ion-header>
      <ion-content class="ion-padding">
        <h1>Page Two</h1>
        <p>Use the back button to navigate to the previous page.</p>
      </ion-content>
    `;
    }
  }

  customElements.define('page-one', PageOne);
  customElements.define('page-two', PageTwo);
</script>
```

**Angular**

`src/app/example.component.html`

```html
<ion-nav [root]="component"></ion-nav>
```

`src/app/example.component.ts`

```ts
import { Component } from '@angular/core';
import { IonNav } from '@ionic/angular';

import { PageOneComponent } from './page-one.component';

@Component({
  selector: 'app-example',
  templateUrl: 'example.component.html',
  styleUrls: ['example.component.css'],
  imports: [IonNav],
})
export class ExampleComponent {
  component = PageOneComponent;
}
```

`src/app/page-one.component.ts`

```ts
import { Component } from '@angular/core';
import { IonButton, IonContent, IonHeader, IonNavLink, IonTitle, IonToolbar } from '@ionic/angular';

import { PageTwoComponent } from './page-two.component';

@Component({
  selector: 'app-page-one',
  template: `
    <ion-header>
      <ion-toolbar>
        <ion-title>Back Button</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">
      <h1>Page One</h1>
      <p>Navigate to the next page to see the back button.</p>
      <ion-nav-link router-direction="forward" [component]="component">
        <ion-button>Navigate</ion-button>
      </ion-nav-link>
    </ion-content>
  `,
  imports: [IonButton, IonContent, IonHeader, IonNavLink, IonTitle, IonToolbar],
})
export class PageOneComponent {
  component = PageTwoComponent;
}
```

`src/app/page-two.component.ts`

```ts
import { Component } from '@angular/core';
import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular';

import { addIcons } from 'ionicons';
import { caretBack } from 'ionicons/icons';

@Component({
  selector: 'app-page-two',
  template: `
    <ion-header>
      <ion-toolbar>
        <ion-buttons slot="start">
          <ion-back-button text="Previous" icon="caret-back"></ion-back-button>
        </ion-buttons>
        <ion-title>Back Button</ion-title>
      </ion-toolbar>
    </ion-header>
    <ion-content class="ion-padding">
      <h1>Page Two</h1>
      <p>Use the back button to navigate to the previous page.</p>
    </ion-content>
  `,
  imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar],
})
export class PageTwoComponent {
  constructor() {
    /**
     * Any icons you want to use in your application
     * can be registered in app.component.ts and then
     * referenced by name anywhere in your application.
     */
    addIcons({ caretBack });
  }
}
```

**React**

`src/main.tsx`

```tsx
import React from 'react';
import { IonNav } from '@ionic/react';

import PageOne from './page-one';

function Example() {
  return <IonNav root={() => <PageOne />}></IonNav>;
}
export default Example;
```

`src/page-one.tsx`

```tsx
import React from 'react';
import { IonButton, IonHeader, IonContent, IonNavLink, IonToolbar, IonTitle } from '@ionic/react';

import PageTwo from './page-two';

function PageOne() {
  return (
    <>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Back Button</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent className="ion-padding">
        <h1>Page One</h1>
        <p>Navigate to the next page to see the back button.</p>
        <IonNavLink routerDirection="forward" component={() => <PageTwo />}>
          <IonButton>Navigate</IonButton>
        </IonNavLink>
      </IonContent>
    </>
  );
}

export default PageOne;
```

`src/page-two.tsx`

```tsx
import React from 'react';
import { IonBackButton, IonButtons, IonHeader, IonContent, IonToolbar, IonTitle } from '@ionic/react';
import { caretBack } from 'ionicons/icons';

function PageTwo() {
  return (
    <>
      <IonHeader>
        <IonToolbar>
          <IonButtons slot="start">
            <IonBackButton text="Previous" icon={caretBack}></IonBackButton>
          </IonButtons>
          <IonTitle>Back Button</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent className="ion-padding">
        <h1>Page Two</h1>
        <p>Use the back button to navigate to the previous page.</p>
      </IonContent>
    </>
  );
}

export default PageTwo;
```

**Vue**

`src/components/Example.vue`

```html
<template>
  <ion-nav :root="component"></ion-nav>
</template>

<script setup lang="ts">
  import { IonNav } from '@ionic/vue';
  import PageOne from './PageOne.vue';

  const component = PageOne;
</script>
```

`src/components/PageOne.vue`

```html
<template>
  <ion-header>
    <ion-toolbar>
      <ion-title>Back Button</ion-title>
    </ion-toolbar>
  </ion-header>
  <ion-content class="ion-padding">
    <h1>Page One</h1>
    <p>Navigate to the next page to see the back button.</p>
    <ion-nav-link router-direction="forward" :component="component">
      <ion-button>Navigate</ion-button>
    </ion-nav-link>
  </ion-content>
</template>

<script setup lang="ts">
  import { IonHeader, IonTitle, IonToolbar, IonContent, IonNavLink, IonButton } from '@ionic/vue';
  import PageTwo from './PageTwo.vue';

  const component = PageTwo;
</script>
```

`src/components/PageTwo.vue`

```html
<template>
  <ion-header>
    <ion-toolbar>
      <ion-buttons slot="start">
        <ion-back-button text="Previous" :icon="caretBack"></ion-back-button>
      </ion-buttons>
      <ion-title>Back Button</ion-title>
    </ion-toolbar>
  </ion-header>
  <ion-content class="ion-padding">
    <h1>Page Two</h1>
    <p>Use the back button to navigate to the previous page.</p>
  </ion-content>
</template>

<script setup lang="ts">
  import { IonHeader, IonTitle, IonToolbar, IonContent, IonButtons, IonBackButton } from '@ionic/vue';
  import { caretBack } from 'ionicons/icons';
</script>
```

## Default Back History

Occasionally an app may need to show the back button and navigate back when there is no history. This can be done by setting the `defaultHref` on the back button to a path. In order to use `defaultHref`, the app must contain a router with paths set.

## Properties

### color

**Description**: The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics.md).

**Attribute**: `color`

**Type**: `"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined`

**Default**: `undefined`

### defaultHref

**Description**: The url to navigate back to by default when there is no history.

**Attribute**: `default-href`

**Type**: `string | undefined`

**Default**: `undefined`

### disabled

**Description**: If `true`, the user cannot interact with the button.

**Attribute**: `disabled`

**Type**: `boolean`

**Default**: `false`

### icon

**Description**: The built-in named SVG icon name or the exact `src` of an SVG file to use for the back button.

**Attribute**: `icon`

**Type**: `null | string | undefined`

**Default**: `undefined`

### mode

**Description**: The mode determines which platform styles to use. This is a [virtual property](/docs/core-concepts/fundamentals.md#virtual-properties) that is set once during initialization and will not update if you change its value after the initial render.

**Attribute**: `mode`

**Type**: `"ios" | "md"`

**Default**: `undefined`

### routerAnimation

**Description**: When using a router, it specifies the transition animation when navigating to another page.

**Attribute**: `undefined`

**Type**: `((baseEl: any, opts?: any) => Animation) | undefined`

**Default**: `undefined`

### text

**Description**: The text to display in the back button.

**Attribute**: `text`

**Type**: `null | string | undefined`

**Default**: `undefined`

### type

**Description**: The type of the button.

**Attribute**: `type`

**Type**: `"button" | "reset" | "submit"`

**Default**: `'button'`

## Events

No events available for this component.

## Methods

No public methods available for this component.

## CSS Shadow Parts

| Name | Description |
| --- | --- |
| `icon` | The back button icon (uses ion-icon). |
| `native` | The native HTML button element that wraps all child elements. |
| `text` | The back button text. |

## CSS Custom Properties

**iOS**

| Name | Description |
| --- | --- |
| `--background` | Background of the button |
| `--background-focused` | Background of the button when focused with the tab key |
| `--background-focused-opacity` | Opacity of the button background when focused with the tab key |
| `--background-hover` | Background of the button on hover |
| `--background-hover-opacity` | Opacity of the background on hover |
| `--border-radius` | Border radius of the button |
| `--color` | Text color of the button |
| `--color-focused` | Text color of the button when focused with the tab key |
| `--color-hover` | Text color of the button on hover |
| `--icon-font-size` | Font size of the button icon |
| `--icon-font-weight` | Font weight of the button icon |
| `--icon-margin-bottom` | Bottom margin of the button icon |
| `--icon-margin-end` | Right margin if direction is left-to-right, and left margin if direction is right-to-left of the button icon |
| `--icon-margin-start` | Left margin if direction is left-to-right, and right margin if direction is right-to-left of the button icon |
| `--icon-margin-top` | Top margin of the button icon |
| `--icon-padding-bottom` | Bottom padding of the button icon |
| `--icon-padding-end` | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the button icon |
| `--icon-padding-start` | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the button icon |
| `--icon-padding-top` | Top padding of the button icon |
| `--margin-bottom` | Bottom margin of the button |
| `--margin-end` | Right margin if direction is left-to-right, and left margin if direction is right-to-left of the button |
| `--margin-start` | Left margin if direction is left-to-right, and right margin if direction is right-to-left of the button |
| `--margin-top` | Top margin of the button |
| `--min-height` | Minimum height of the button |
| `--min-width` | Minimum width of the button |
| `--opacity` | Opacity of the button |
| `--padding-bottom` | Bottom padding of the button |
| `--padding-end` | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the button |
| `--padding-start` | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the button |
| `--padding-top` | Top padding of the button |
| `--ripple-color` | Color of the button ripple effect |
| `--transition` | Transition of the button |

**MD**

| Name | Description |
| --- | --- |
| `--background` | Background of the button |
| `--background-focused` | Background of the button when focused with the tab key |
| `--background-focused-opacity` | Opacity of the button background when focused with the tab key |
| `--background-hover` | Background of the button on hover |
| `--background-hover-opacity` | Opacity of the background on hover |
| `--border-radius` | Border radius of the button |
| `--color` | Text color of the button |
| `--color-focused` | Text color of the button when focused with the tab key |
| `--color-hover` | Text color of the button on hover |
| `--icon-font-size` | Font size of the button icon |
| `--icon-font-weight` | Font weight of the button icon |
| `--icon-margin-bottom` | Bottom margin of the button icon |
| `--icon-margin-end` | Right margin if direction is left-to-right, and left margin if direction is right-to-left of the button icon |
| `--icon-margin-start` | Left margin if direction is left-to-right, and right margin if direction is right-to-left of the button icon |
| `--icon-margin-top` | Top margin of the button icon |
| `--icon-padding-bottom` | Bottom padding of the button icon |
| `--icon-padding-end` | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the button icon |
| `--icon-padding-start` | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the button icon |
| `--icon-padding-top` | Top padding of the button icon |
| `--margin-bottom` | Bottom margin of the button |
| `--margin-end` | Right margin if direction is left-to-right, and left margin if direction is right-to-left of the button |
| `--margin-start` | Left margin if direction is left-to-right, and right margin if direction is right-to-left of the button |
| `--margin-top` | Top margin of the button |
| `--min-height` | Minimum height of the button |
| `--min-width` | Minimum width of the button |
| `--opacity` | Opacity of the button |
| `--padding-bottom` | Bottom padding of the button |
| `--padding-end` | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the button |
| `--padding-start` | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the button |
| `--padding-top` | Top padding of the button |
| `--ripple-color` | Color of the button ripple effect |
| `--transition` | Transition of the button |

## Slots

No slots available for this component.