Skip to main content

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.

Anchor to OverviewOverview

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

Anchor to Quick StartQuick Start

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

Enable navigation transitions

App.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>
)
}

Anchor to Navigation ComponentsNavigation Components

Shop Minis provides two main ways to navigate with transitions:

Anchor to TransitionLink ComponentTransitionLink Component

Use TransitionLink for declarative navigation links:

API ReferenceTransitionLink API

Using TransitionLink

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>
)
}

Anchor to Programmatic NavigationProgrammatic Navigation

Anchor to useNavigateWithTransition HookuseNavigateWithTransition Hook

For programmatic navigation with transitions, use the useNavigateWithTransition hook:

API ReferenceuseNavigateWithTransition API

Using the navigation hook

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>
)
}

Anchor to Back NavigationBack 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

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

const navigateWithTransition = useNavigateWithTransition()

// Go back one page
navigateWithTransition(-1)

Anchor to Best PracticesBest 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

Anchor to AccessibilityAccessibility

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

Anchor to Navigation GuardsNavigation Guards

You can prevent navigation by using custom click handlers:

Conditional navigation

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>
)
}

Anchor to TroubleshootingTroubleshooting

Anchor to Transitions Not WorkingTransitions 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

Anchor to Animation IssuesAnimation 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
Was this page helpful?