> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neynar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Back Navigation

> Support back navigation in your mini app

Integrate with a back navigation control provided by the Farcaster client.

## Usage

If your application is already using [browser-based navigation](#web-navigation-integration), you can
integrate in one line with:

```ts theme={"system"}
await sdk.back.enableWebNavigation();
```

That's it! When there is a page to go back to a [back control](#back-control) will be made
available to the user.

Otherwise, you can set a custom back handler and show the back control:

```ts theme={"system"}
sdk.back.onback = () => {
  // trigger back in your app
}

await sdk.back.show();
```

## Back control

The back control will vary depending on the user's device and platform but will
generally follow:

* a clickable button in the header on web
* a horizontal swipe left gesture on iOS
* the Android native back control on Android which could be a swipe left
  gesture combined with a virtual or physical button depending on the device

## Web Navigation integration

The SDK can automatically integrate with web navigation APIs.

### `enableWebNavigation()`

Enables automatic integration with the browser's navigation system. This will:

* Use the modern Navigation API when available; the back button will automatically
  be shown and hidden based on the value of `canGoBack`.
* Fall back to the History API in browsers where Navigation is [not
  supported](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API#browser_compatibility)
  ; the back button will always be shown.

```ts theme={"system"}
await sdk.back.enableWebNavigation();
```

### `disableWebNavigation()`

Disables web navigation integration.

```ts theme={"system"}
await sdk.back.disableWebNavigation();
```

## Properties

### `enabled`

* **Type**: `boolean`
* **Description**: Whether back navigation is currently enabled

### `onback`

* **Type**: `() => unknown`
* **Description**: Function to call when a back event is triggered. You don't need to
  set this when using `enableWebNavigation`.

## Methods

### `show()`

Makes the back button visible.

```ts theme={"system"}
await sdk.back.show();
```

### `hide()`

Hides the back button.

```ts theme={"system"}
await sdk.back.hide();
```

## Events

When a user triggers the back control the SDK will emit an
`backNavigationTriggered` event. You can add an event listener on `sdk` or use
`sdk.back.onback` to respond to these events.

If you are using `enableWebNavigation` this event will automatically be
listened to and trigger the browser to navigate. Otherwise you should listen
for this event and respond to it as appropriate for your application.

## Availability

You can check whether the Farcaster client rendering your app supports a back control:

```ts theme={"system"}
import { sdk } from '@farcaster/miniapp-sdk'

const capabilities = await sdk.getCapabilities()

if (capabilities.includes('back')) {
  await sdk.back.enableWebNavigation();
} else {
  // show a back button within your app
}
```

## Example: Web Navigation

```ts theme={"system"}
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Enable web navigation integration
    sdk.back.enableWebNavigation();
  }, []);

  return (
    <div>
      {/* Your app content */}
    </div>
  );
}
```

## Example: Manual

```ts theme={"system"}
function NavigationExample() {
  const [currentPage, setCurrentPage] = useState('home');

  useEffect(() => {
    // Update back button based on current page
    if (currentPage === 'home') {
      sdk.back.hide(); // Nothing to go back to on home
    } else {
      sdk.back.show(); // Show back button on sub-pages
    }
  }, [currentPage]);

  const handleBack = () => {
    if (currentPage !== 'home') {
      setCurrentPage('home');
    }
  };

  // Listen for back navigation events
  useEffect(() => {
    sdk.on('backNavigationTriggered', handleBack);
    return () => sdk.off('backNavigationTriggered', handleBack);
  }, [currentPage]);

  return (
    <div>
      {currentPage === 'home' ? (
        <HomePage onNavigate={setCurrentPage} />
      ) : (
        <SubPage />
      )}
    </div>
  );
}
```