<Stack />

This component should only be rendered inside a _layout.tsx file, where it will serve as the location that children will render for routes below the layout.

Stack is simply a React Navigation Native Stack view and accepts the same props as React Navigation.

import { Stack } from 'one'
import { Button } from 'react-native'

export default function Layout() {
  return (
    <Stack
      screenOptions={{
        headerRight() {
          return (
            <Button label="Settings" />
          )
        },
      }}
    />
  )
}

You can customize the children of the Stack in your layout by passing a children prop to Stack has Stack.Screen elements, like so:

import { Stack } from 'one'

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: 'Feed' }} />
      <Stack.Screen name="[id]" options={{ title: 'Post' }} />
      <Stack.Screen
        name="sheet"
        options={{
          presentation: 'formSheet',
          gestureDirection: 'vertical',
          animation: 'slide_from_bottom',
          headerShown: false,
        }}
      />
    </Stack>
  )
}

The name must match the full name of the file inside app, without the extension but including groups.

In this example we are setting index, [id], and sheet screens, which would correspond to index.tsx and [id].tsx and sheet.tsx pages in the same directory.

This is a convenient way to configure settings for each page up front, but you could also render Stack.Screen inside each individual page so you can access data loaded inside that page. The upside of doing it in the layout is that it will configure things before any stack animation runs on enter, with the downside being that you can’t access page-level data.

The options property passes to the React Navigation NativeStack, and so takes the same options.

For more declarative header configuration, use the compositional API with Stack.Header and its child components:

import { Stack } from 'one'

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index">
        <Stack.Header blurEffect="regular">
          <Stack.Header.Title large>Articles</Stack.Header.Title>
          <Stack.Header.SearchBar placeholder="Search..." />
        </Stack.Header>
      </Stack.Screen>

      <Stack.Screen name="[id]">
        <Stack.Header>
          <Stack.Header.Title>Post</Stack.Header.Title>
          <Stack.Header.Right asChild>
            <ShareButton />
          </Stack.Header.Right>
        </Stack.Header>
      </Stack.Screen>
    </Stack>
  )
}

Stack.Header

The container for header configuration. Props:

• hidden - Hide the header entirely
• blurEffect - iOS blur effect ('regular', 'prominent', 'systemMaterial', etc.)
• asChild - Render a completely custom header component
• style - Style with backgroundColor, shadowColor (set to 'transparent' to hide)
• largeStyle - Style for large title mode

Stack.Header.Title

Configure the header title:

<Stack.Header.Title large>My Title</Stack.Header.Title>

Props:

• children - The title text
• large - Enable iOS large title mode
• style - Text style (fontWeight, fontSize, color, textAlign)

Stack.Header.BackButton

Configure the back button:

<Stack.Header.BackButton hidden />
<Stack.Header.BackButton displayMode="minimal">Back</Stack.Header.BackButton>

Props:

• children - Custom back button text
• hidden - Hide the back button
• displayMode - 'default', 'generic', or 'minimal'
• withMenu - Enable long-press menu on iOS

Stack.Header.Left / Stack.Header.Right

Add custom components to the header:

<Stack.Header.Left asChild>
  <MenuButton />
</Stack.Header.Left>

<Stack.Header.Right asChild>
  <SettingsButton />
</Stack.Header.Right>

Props:

• asChild - Required to render custom children
• children - Your custom component

Stack.Header.SearchBar

Add an iOS-style search bar:

<Stack.Header.SearchBar
  placeholder="Search articles..."
  autoCapitalize="none"
  placement="stacked"
/>

Props:

• placeholder - Placeholder text
• autoCapitalize - 'none', 'words', 'sentences', 'characters'
• placement - 'automatic' or 'stacked'
• hideWhenScrolling - Hide when scrolling
• obscureBackground - Obscure background when active

Default Header for All Screens

You can set a default header for all screens by placing Stack.Header directly inside Stack:

<Stack>
  <Stack.Header blurEffect="regular">
    <Stack.Header.BackButton displayMode="minimal" />
  </Stack.Header>

  <Stack.Screen name="index" options={{ title: 'Home' }} />
  <Stack.Screen name="profile" options={{ title: 'Profile' }} />
</Stack>

On native, presentations like formSheet, pageSheet, and modal are handled by react-native-screens and render as real native sheets. On web there is no built-in equivalent - by default an overlay route shows as a card.

The render prop on <Stack> lets you plug in any sheet or modal library to render overlay routes on web. Tamagui Sheet, Vaul, Radix Dialog, or a hand-rolled element all work.

import { Stack, type StackRender } from 'one'
import { Sheet } from 'tamagui'

// Hoist outside the layout to keep identity stable across re-renders.
const render: StackRender = {
  web: ({ children, open, dismiss, dismissible, sheetAllowedDetents }) => (
    <Sheet
      modal
      open={open}
      onOpenChange={(o) => !o && dismiss()}
      dismissOnSnapToBottom={dismissible}
      snapPoints={sheetAllowedDetents}
    >
      <Sheet.Overlay />
      <Sheet.Frame>{children}</Sheet.Frame>
    </Sheet>
  ),
}

export default function Layout() {
  return (
    <Stack render={render}>
      <Stack.Screen
        name="filters"
        options={{
          presentation: 'formSheet',
          sheetAllowedDetents: [0.5, 1],
          sheetGrabberVisible: true,
        }}
      />
    </Stack>
  )
}

How the render is invoked

The render component receives the overlay route’s content as children along with normalized props:

• open: boolean - whether the overlay should be visible. Toggles as you navigate.
• dismiss(): void - call after your close animation completes. Triggers StackActions.pop.
• dismissible: boolean - matches options.gestureEnabled.
• presentation - the route’s presentation option.
• routeKey, routeName - the route identity.
• All sheet detent options (sheetAllowedDetents, sheetGrabberVisible, sheetCornerRadius, sheetInitialDetentIndex, sheetLargestUndimmedDetentIndex, sheetExpandsWhenScrolledToEdge) pass through unchanged.

Per-route override

Pass render inside options to override for a single route:

<Stack render={defaultRender}>
  <Stack.Screen
    name="filters"
    options={{
      presentation: 'formSheet',
      render: { web: SpecialFilterChrome },
    }}
  />
</Stack>

Resolution: per-route options.render → <Stack render> → setupRendering global → default (renders inline).

Global setup via the setup file

If every <Stack> in your app should use the same overlay render, register it once from your setup file:

import { setupRendering } from 'one'
import { Sheet } from 'tamagui'

setupRendering({
  Stack: {
    web: ({ children, open, dismiss, sheetAllowedDetents }) => (
      <Sheet modal open={open} onOpenChange={(o) => !o && dismiss()} snapPoints={sheetAllowedDetents}>
        <Sheet.Overlay />
        <Sheet.Frame>{children}</Sheet.Frame>
      </Sheet>
    ),
  },
})

Wire the setup file in vite.config.ts:

import { one } from 'one/vite'

export default {
  plugins: [
    one({
      setupFile: './app/setup.ts',
    }),
  ],
}

You can split per environment if needed: setupFile: { client: './client.ts', server: './server.ts', native: './native.ts' }.

Keeping overlay routes mounted across dismissal

By default, dismissing an overlay route pops it from the navigation state and React unmounts the route component. To preserve state (form values, useId, useState, refs) across close → reopen, set keepMounted: true on the screen options:

<Stack.Screen
  name="settings"
  options={{
    presentation: 'formSheet',
    keepMounted: true,
  }}
/>

When keepMounted is on:

• The route’s React subtree is captured the first time it mounts and held in a persistent slot.
• On dismissal the route is popped from navigation state (URL stays correct) but the captured subtree keeps rendering - the render component receives open: false.
• On re-navigation the same component instance is reused; useId returns the same value, useState retains its value, refs are preserved.

The render component must keep children in the React tree when open: false - typically by toggling visibility rather than conditionally rendering. Tamagui Sheet’s modal mode does this automatically. A render that returns null when closed will unmount the children regardless of keepMounted.

// ❌ unmounts on close - keepMounted has no effect
const render: StackRender = {
  web: ({ children, open }) => (open ? <div>{children}</div> : null),
}

// ✅ keeps children mounted, just hidden
const render: StackRender = {
  web: ({ children, open, dismiss }) => (
    <Sheet modal open={open} onOpenChange={(o) => !o && dismiss()}>
      <Sheet.Frame>{children}</Sheet.Frame>
    </Sheet>
  ),
}

Caveats:

• The route subtree is captured at first mount, so route params are frozen at the first values. Best for stable, parameter-free overlays (settings, persistent filters, command palettes). Don’t use on [id]-style dynamic routes.
• The persistent slot only lives as long as the <Stack> itself.