Progress & Resuming

For long tours, users may navigate away mid-tour and want to resume where they left off. Trailguide supports this with the resumable option and the tourStorage API.

Enable resuming

Pass resumable: true to useTrailManager or useRegisterTour:

const { isActive, dismiss } = useTrailManager(longTour, {
  once: true,
  resumable: true,
})

When resumable is true:

• onStepChange saves the current step index to localStorage via tourStorage.saveProgress(key, index)
• When the tour is shown again (e.g. the user returns and clicks the help button), it resumes from the saved step
• On completion or skip, the saved progress is cleared

Manual progress control

You can read and write progress directly using tourStorage:

import { tourStorage } from '@trailguide/core'
 
// Get the step the user last reached (or null if no progress)
const savedStep = tourStorage.getProgress('onboarding')
 
// Save progress manually (e.g. in your own onStepChange handler)
tourStorage.saveProgress('onboarding', 3)
 
// Clear progress without clearing completion
tourStorage.clearProgress('onboarding')

Navigate to a specific step

Use goToStep(index) to jump to any step programmatically:

const { show, goToStep } = useTrailManager(tour, { once: true })
 
// Start at step 3 (0-indexed)
const handleResume = () => {
  show()
  goToStep(3)
}

useTrailManager does this automatically when resumable: true.

Storage keys

tourStorage uses localStorage with the prefix trailguide:. Keys used:

The default key used by useTrailManager is trailguide:managed:{trail.id}. Pass a custom storageKey to override:

useTrailManager(tour, {
  once: true,
  resumable: true,
  storageKey: 'myapp:tours:onboarding-v2',
})

Reset everything

import { tourStorage } from '@trailguide/core'
 
// Reset a single tour (clears completion + progress)
tourStorage.reset('onboarding')
 
// Reset all Trailguide state from localStorage
tourStorage.resetAll()