Documentation
Playground

$navigate

Navigate between screens programmatically.

Basic Usage

$navigate("/login")
$navigate("/profile/${userId}")
$navigate("/home")

With Path Parameters

Pass dynamic values in the URL:

<Button onClick={() => $navigate("/user/${user.id}")}>
  View Profile
</Button>

With State

Pass data to the next screen without adding it to the URL:

$navigate("/show/${id}", state = {
  name: show.name,
  poster: show.poster
})

// In the destination screen
val previewName = $route.state?.name
val previewPoster = $route.state?.poster

This is useful for:

  • Preview data while loading full details
  • Passing non-serializable data between screens
  • Avoiding long URLs

File-Based Routing

Routes are automatically generated from your src/routes/ folder structure:

routes/
├── +screen.wh              # → /
├── login/+screen.wh         # → /login
├── user/[id]/+screen.wh     # → /user/:id
└── posts/[slug]/+screen.wh  # → /posts/:slug

Dynamic Routes

Use [param] folders for dynamic segments:

// Navigate to user profile
$navigate("/user/123")

// In user/[id]/+screen.wh
val userId = $route.params.id  // "123"

Navigation from Components

Use $navigate anywhere, including event handlers:

<Column class="gap-8">
  @for (show in shows) {
    <Card onClick={() => $navigate("/show/${show.id}")}>
      <Image src={show.poster} />
      <Text>{show.name}</Text>
    </Card>
  }
</Column>

Layouts

Wrap screens with shared UI using +layout.wh:

// routes/+layout.wh (root layout)
<Scaffold>
  <TopAppBar title="My App" />
  <slot />  
  <BottomNavigation>
    <Button onClick={() => $navigate("/")}>Home</Button>
    <Button onClick={() => $navigate("/search")}>Search</Button>
    <Button onClick={() => $navigate("/profile")}>Profile</Button>
  </BottomNavigation>
</Scaffold>

Breaking Layout Inheritance

Skip layouts for specific screens:

  • +screen@.wh - No layouts at all
  • +screen@root.wh - Only root layout, skip intermediate layouts

Back Navigation

The Android back button automatically works. To handle back programmatically:

// Implementation coming soon
// $navigate.back()

Whitehall generates a type-safe Routes object for navigation. Use $routes alias to access it.

See Also