Navigation

Navigation runs on the same universal router as everything else. In the browser it moves between pages without a full reload; on the server it produces the first render. You write links and calls once, and they behave correctly in every rendering mode.

#Declarative: StoneLink

StoneLink is the link. In SPA and SSR it navigates client-side; where a real navigation is needed, it falls back to one. Give it a path or a generated URL.

import { StoneLink, useRouter, useRoute } from '@stone-js/use-react'

export function Nav () {
  const router = useRouter()
  const route = useRoute()
  return (
    <nav>
      <StoneLink to='/tasks' className={route?.name === 'tasks.list' ? 'active' : ''}>Tasks</StoneLink>
      <StoneLink to={router.generate({ name: 'tasks.show', params: { id: 1 } })}>First</StoneLink>
    </nav>
  )
}

#Programmatic navigation

When navigation follows an action, ask the router to navigate. Generate the target by name so the path stays in one place.

const router = useRouter()

async function onSubmit (values: NewTask) {
  const task = await api.create(values)
  router.navigate(router.generate({ name: 'tasks.show', params: { id: task.id } }))
}

#Knowing where you are

useRoute() gives the active route, which is how you highlight the current link, read a param, or branch on the page. It updates as navigation happens.

#Scroll restoration

Client navigation restores scroll position the way users expect: to the top on a new page, back to where they were on back/forward. Enable it once; it is not something you wire per link.

import { setupScrollRestoration } from '@stone-js/use-react'

setupScrollRestoration()   // top on navigate, remembered position on back/forward

#View transitions

Animate between pages with the View Transitions API, a cross-fade, a shared element, without hand-rolling animation state. It degrades gracefully where the API is absent and respects prefers-reduced-motion.

import { renderWithTransition } from '@stone-js/use-react'

// Wrap the render so route changes animate where the browser supports it.
renderWithTransition(app)