---
title: Navigation transitions
description: >
  Learn how to implement smooth navigation transitions in your Shop Mini. This
  guide covers MinisRouter setup, TransitionLink usage, and custom navigation
  patterns for creating fluid, app-like experiences.
api_name: shop-minis
source_url:
  html: 'https://shopify.dev/docs/api/shop-minis/navigation-transitions'
  md: 'https://shopify.dev/docs/api/shop-minis/navigation-transitions.md'
---

# Navigation transitions

Learn how to implement smooth navigation transitions in your Shop Mini. This guide covers MinisRouter setup, TransitionLink usage, and custom navigation patterns for creating fluid, app-like experiences.

***

## Overview

Shop Minis support smooth navigation transitions, providing native app-like page transitions. When enabled, navigations slide smoothly between pages with configurable animations.

Key features:

* **Automatic animations**: Forward navigation slides from right, back navigation slides from left
* **Gesture support**: Detects iOS swipe gestures and Android back button for appropriate animations

***

## Quick Start

To enable navigation transitions in your Shop Mini, wrap your app with MinisRouter and set the `viewTransitions` prop:

## Enable navigation transitions

## App.tsx

```tsx
import {MinisRouter} from '@shopify/shop-minis-react'
import {Routes, Route} from 'react-router'


function App() {
  return (
    <MinisRouter viewTransitions>
      <Routes>
        <Route path="/" element={<HomePage />} />
        <Route path="/products/:id" element={<ProductPage />} />
      </Routes>
    </MinisRouter>
  )
}
```

***

## Navigation Components

Shop Minis provides two main ways to navigate with transitions:

### Transition​Link Component

Use TransitionLink for declarative navigation links:

[- TransitionLink API](./shop-minis/components/TransitionLink)

## Using TransitionLink

```tsx
import {TransitionLink} from '@shopify/shop-minis-react'


function ProductCard({product}) {
  return (
    <div className="product-card">
      <TransitionLink to={`/products/${product.id}`}>
        <img src={product.image} alt={product.title} />
        <h3>{product.title}</h3>
      </TransitionLink>
    </div>
  )
}
```

***

## Programmatic Navigation

### use​Navigate​With​Transition Hook

For programmatic navigation with transitions, use the useNavigateWithTransition hook:

[- useNavigateWithTransition API](./shop-minis/hooks/useNavigateWithTransition)

## Using the navigation hook

```tsx
import {useNavigateWithTransition} from '@shopify/shop-minis-react'
import {Button} from '@shopify/shop-minis-react'


function CheckoutButton() {
  const navigateWithTransition = useNavigateWithTransition()


  const handleClick = () => {
    // Perform validation or API calls
    // Navigate with smooth transition
    navigateWithTransition('/checkout')
  }


  return (
    <Button onClick={handleClick}>
      Proceed to Checkout
    </Button>
  )
}
```

***

## Back Navigation

When navigating back (pop/back button), the old page slides right and fades out, and the previous page slides in from the left. This is automatically triggered by iOS swipe gesture or Android back button. You can programmatically navigate back by using the `useNavigateWithTransition` hook with a negative number.

## Back Navigation

```tsx
import {useNavigateWithTransition} from '@shopify/shop-minis-react'


const navigateWithTransition = useNavigateWithTransition()


// Go back one page
navigateWithTransition(-1)
```

***

## Best Practices

* **Use TransitionLink for static navigation**: TransitionLink is optimized for declarative navigation
* **Batch state updates**: Perform state updates before navigation to avoid mid-transition renders
* **Respect prefers-reduced-motion**: The default styles disable animations when users prefer reduced motion

### Accessibility

* Transitions automatically respect the `prefers-reduced-motion` media query
* Ensure focus management across page transitions
* Provide clear visual feedback during navigation

***

## Navigation Guards

You can prevent navigation by using custom click handlers:

## Conditional navigation

```tsx
import {TransitionLink} from '@shopify/shop-minis-react'


function SecureLink() {
  var canNavigateThere = false


  return (
    <TransitionLink
      to="/account"
      onClick={(e) => {
        if (!canNavigateThere) {
          e.preventDefault()
          // Show error modal instead
          console.error('You are not authorized to navigate there')
        }
      }}
    >
      Protected Page
    </TransitionLink>
  )
}
```

***

## Troubleshooting

### Transitions Not Working

1. **Check viewTransitions prop**: Ensure MinisRouter has `viewTransitions` enabled
2. **Navigating backwards**: Check if you are using the `useNavigateWithTransition(-1)` hook to navigate backwards
3. **Absolute URLs**: TransitionLink warns about absolute URLs - use relative paths

### Animation Issues

* **Jumpy transitions**: Ensure consistent layouts between pages
* **Missing animations**: Check CSS isn't overriding transition styles
* **Performance**: Large DOM changes during transition can cause stuttering

***