Beta

System

wwwwwwwwwwwwwwwwwww

Introduction

Installation

Layouts

Layout files can be placed in any folder inside the ./app directory. They serve as the frame for the routes contained within that folder, and they can nest inside of each other if you place them in sub-directories.

_layout.tsx

Wraps all files in this directory and below

index.tsx

Matches "/"

blog

_layout.tsx

A custom sub-layout for all /blog pages

index.tsx

Matches "/blog"

[slug].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

Layouts must render one of the following to show the matched pages that exist in their directory:

Slot: Directly show sub-route with no frame.
Stack: Creates a React Navigation Stack of sub-routes.
Tabs: Creates a React Navigation BottomTabs with sub-routes.
Drawer: Creates a React Navigation Drawer with sub-routes.

This looks something like this at the simplest:

app/_layout.tsx

import { Slot } from 'one'

export default function Layout() {
  return <Slot />
}

Layout Loaders

Layouts can export a loader function just like pages. This is useful for fetching data that’s shared across all routes in that layout:

app/docs/_layout.tsx

import { useLoader, Slot } from 'one'

export async function loader() {
  return {
    navItems: await fetchDocsNavigation(),
    version: await fetchCurrentVersion(),
  }
}

export default function DocsLayout() {
  const data = useLoader(loader)

  return (
    <div>
      <Sidebar items={data.navItems} version={data.version} />
      <main>
        <Slot />
      </main>
    </div>
  )
}

Layout loaders run in parallel with page loaders for optimal performance. All matched route loaders (root layout → nested layouts → page) execute simultaneously.

Accessing Page Data from a Layout

Use useMatches to access the current page’s loader data from a layout:

app/docs/_layout.tsx

import { useMatches, Slot } from 'one'

export default function DocsLayout() {
  const matches = useMatches()
  const pageMatch = matches[matches.length - 1]
  const headings = pageMatch?.loaderData?.headings

  return (
    <div>
      <main>
        <Slot />
      </main>
      <TableOfContents headings={headings} />
    </div>
  )
}

See useMatches for more details.

Layout Loader Caching

On client-side navigation, layout loaders do not re-run - their data is cached from the initial page load. Only the destination page’s loader runs. This is intentional for performance, as layout data (navigation items, site config) rarely changes.

When layout loaders DO re-run:

Full page loads (initial visit, hard refresh)
SSR page requests (each request runs all matched loaders on server)
After calling window.location.reload()

When layout loaders DON’T re-run:

Client-side navigation via <Link> or useRouter().push()

If you need fresh layout data, you can trigger a full page navigation instead of client-side navigation, or store frequently-changing data in the page loader and access it via useMatches().

If you need to access the current route params in a layout, you can use the useActiveParams hook.

Root Layout

The root layout on web controls the entire page, from <html> on down. You can optionally return html, body, and head elements in your app/_layout.tsx and they will “just work” - on web, it will be output, and on native it won’t so as to avoid rendering errors:

app/_layout.tsx

import { Slot } from 'one'

export default function Layout() {
  return (
    <html lang="en-US">
      <head>
        <meta charSet="utf-8" />
      </head>

      <body>
        <Slot />
      </body>
    </html>
  )
}

Note - you should have both a lang property on your html tag, and a <meta charSet /> tag in your head. Otherwise, React can have hydration re-rendering issues.

Layout Render Modes

Layouts support render mode suffixes just like pages. This is especially useful for the root layout:

Terminal

app/
├── _layout+ssg.tsx     # Pre-rendered at build time
├── _layout+ssr.tsx     # Rendered per-request on server
└── _layout.tsx         # Client-rendered (default)

When to use layout render modes:

_layout+ssg.tsx - Best for static navigation, site chrome, and head tags. The layout HTML is generated once at build time and served instantly for all pages.
_layout+ssr.tsx - Use when your layout needs dynamic data per-request (e.g., auth state in the nav, user-specific content). The layout loader runs on each request.
_layout.tsx (no suffix) - Client-rendered. Use when the layout has no server requirements.

SPA pages with SSG/SSR layouts:

When an SPA page has a parent layout with +ssg or +ssr render mode, One automatically renders the layout shell on the server. This gives users immediate visual content (navigation, sidebar, head tags, CSS) while page content remains client-rendered.

app/_layout+ssg.tsx

import { Slot } from 'one'

export async function loader() {
  return {
    navItems: ['Home', 'About', 'Contact'],
  }
}

export default function RootLayout() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <title>My App</title>
      </head>
      <body>
        <nav>{/* Navigation renders immediately */}</nav>
        <main>
          <Slot /> {/* SPA page content loads after JS */}
        </main>
      </body>
    </html>
  )
}

With this setup, even dashboard+spa.tsx pages show the nav instantly - only the main content area waits for JavaScript.

useServerHeadInsertion

The root _layout.tsx can use a special hook that allows it to insert tags into your <head /> tag after server rendering finishes. This is an edge-case that is mostly only useful for CSS-in-JS libraries. You can use it like so:

import { Slot, useServerHeadInsertion } from 'one'

export default function Layout() {
  useServerHeadInsertion(() => {
    // this will run after the entire page renders
    // return a single React.ReactElement that will be spliced into your <head />
    return <style>{renderCSS()}</style>
  })

  return (
    <html>
      <Slot />
    </html>
  )
}

Groups and layouts

If you’d like to logically group together some pages without creating a sub-route, you can use a group folder by naming it like so:

_layout.tsx

Wraps all files in this directory and below

index.tsx

Matches "/"

(blog)

_layout.tsx

A custom sub-layout for all /blog pages

blog.tsx

Matches "/blog"

[slug].tsx

Matches a single sub-path of "/blog", like "/blog/hello"

Groups let you add extra layouts. If done right, this gives you a lot of control over how your app feels.

Nested layouts example

A common pattern that apps have is something like Twitter/X, where you have bottom tabs for your “top level” views, but then on some of the bottom tab sections, you want to have a Stack that remembers its state inside just that tab.

This pattern can be incredibly verbose to link together with React Navigation, and takes a bit of tinkering to figure out with One. Since it is common and a useful example, lets walk through how you’d build on using One’s file system routing.

Here’s our file structure:

_layout.tsx

Where our Tabs layout is defined

notifications.tsx

Matches "/notifications"

profile.tsx

Matches "/profile"

(feed)

_layout.tsx

Where our Stack layout is defined

index.tsx

Matches "/"

post-[id].tsx

Matches routes like "/post-123"

The top level Layout will define our tabs:

app/_layout.tsx

import { Bell, Home, User } from '@tamagui/lucide-icons-2'

export function RootLayout() {
  return (
    <Tabs
      screenOptions={{
        headerShown: false,
      }}
    >
      <Tabs.Screen
        name="(feed)"
        options={{
          title: 'Feed',
          tabBarIcon: ({ color }) => <Home size={20} color={color} />,
        }}
      />

      <Tabs.Screen
        name="notifications"
        options={{
          title: 'Notifications',
          tabBarIcon: ({ color }) => <Bell size={20} color={color} />,
        }}
      />

      <Tabs.Screen
        name="profile"
        options={{
          title: 'Profile',
          tabBarIcon: ({ color }) => <User size={20} color={color} />,
        }}
      />
    </Tabs>
  )
}

This will set us up with three bottom tabs: Feed, Notifications, and Profile. The Notifications and Profile tabs for now will just show their content directly, but inside of the Feed tab, we want to show a stack.

We set up the stack in (feed)/_layout.tsx:

(feed)/_layout.tsx

import { Slot, Stack } from 'one'

export default function FeedLayout() {
  return (
    <>
      {typeof window !== 'undefined' ? (
        <Slot />
      ) : (
        <Stack>
          <Stack.Screen name="index" options={{ title: 'Feed' }} />
          <Stack.Screen name="[id]" options={{ title: 'Post' }} />
        </Stack>
      )}
    </>
  )
}

One thing we’re showing here is that the layout is diverging between web and native. On web, we are showing a Slot, while on Native we show a Stack. This is because browsers feel better without stacks - the native back/forward button serves as our stack controller.

On Native we are defining the configuration for each sub-screen with the Stack.Screen component. The Stack component is a React Navigation native stack navigator and nothing more, it accepts all the props you’d expect.

You’ll notice we are matching the name to the file names names of the sub-routes, without the .tsx extension.

This will get you a nice Stack-inside-Tabs pattern that is common on native apps, all with just two layouts and a few routes.

Limitations

Note that useParams won’t work in layouts, as they are never nested inside a route. Instead, you can use useActiveParams.

PreviousMetro Mode

Overview

Edit this page on GitHub.