Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 50 ยท Nested Routes and Layouts

Nested Routes and Outlet

Nest routes inside parent routes, render children with Outlet, map a URL to a tree of layouts, and see why parent layouts stay mounted between pages.

Look at almost any real application and you will find screens inside screens. A site has a header and, inside it, a section such as "Account". The Account section has a sidebar and, inside that, the Profile, Orders or Billing page. When you move from Orders to Billing, only the innermost part changes: the header and sidebar stay exactly where they are.

React Router models this with nested routes. A route can have child routes, the URL is the parent's path followed by the child's path, and the UI is the parent's component with the child's component placed inside it. The place where the child appears is marked with the <Outlet /> component. In this lesson you will build a nested route tree, follow how a URL turns into a tree of components, and see the practical payoff: parents are not rebuilt when only the child changes. If you built your own Outlet in Client-Side Routing, this lesson is the same idea with the real names and rules.

Parents, children and Outlet

Here is a nested route tree in real React Router code (read-only, because the live editor cannot install packages):

JSX
// App.jsx - React Router (read-only)
import { Routes, Route, Outlet, Link } from 'react-router';

function AppLayout() {
  return (
    <div>
      <header>
        <Link to="/">Home</Link> <Link to="/users">Users</Link>
      </header>
      <main>
        <Outlet />
      </main>
    </div>
  );
}

function UsersLayout() {
  return (
    <section>
      <h2>Users</h2>
      <Outlet />
    </section>
  );
}

export default function App() {
  return (
    <Routes>
      <Route path="/" element={<AppLayout />}>
        <Route index element={<Home />} />
        <Route path="users" element={<UsersLayout />}>
          <Route index element={<UserList />} />
          <Route path=":userId" element={<UserDetail />} />
        </Route>
      </Route>
    </Routes>
  );
}

Read it from the outside in:

  • The outer route has path="/" and renders AppLayout. Its <Outlet /> is the slot for whichever child matches.
  • users is a child of the outer route. Its full URL is /users (the parent's path plus its own). It renders UsersLayout, which has its own Outlet.
  • :userId is a child of users. Its full URL is /users/:userId, and it renders UserDetail in the slot of UsersLayout.
  • The two index routes are the default children. / shows Home inside AppLayout; /users shows UserList inside UsersLayout.

Three rules explain nearly all nested-routing behavior:

  1. Child paths are relative. Write path="users", not path="/users". React Router joins the parent's path and the child's path for you. This also means you can move a whole subtree to a new URL by changing one parent path.
  2. A parent must render <Outlet />. Without it, the children match, but nothing marks where they go, so they never appear. This is the most common nested-routing bug.
  3. A matching URL matches a whole chain. /users/42 matches three routes at once (root, users, :userId), and each one's component renders inside the previous one's Outlet.

Real library or stand-in? The code above is the real API. The live examples run in a sandbox with no packages, so they use a small hand-written router: a list of route objects, a matcher that returns the whole chain of matches, and an Outlet component that renders the next level down. It uses location.hash, so links look like #/users/42. The real router adds ranking, relative links, loaders and much more, but the nesting works the same way.

From URL to UI tree

The diagram shows what happens for the URL /users/42. The router finds the chain of matching routes, and React renders each element inside the previous Outlet:

flowchart TD
    U["URL: /users/42"] --> M["Matches: root, users, :userId"]
    M --> A["AppLayout renders<br/>header and Outlet"]
    A --> B["UsersLayout renders<br/>heading and Outlet"]
    B --> C["UserDetail renders<br/>user 42"]

One URL, three nested components. Each Outlet is the hole the next one fills.

Now run it. The stand-in below has a parent (AppLayout) with its own counter and a text box, so you can check that the parent really is not reset when the child changes.

Nested routes with an Outlet

Click the layout counter a few times and type a word in the box. Now click "Users", then a name. The counter and the text stay as you left them: AppLayout was not unmounted, because React sees the same component at the same position in the tree and keeps its state. Only the part inside the Outlet was swapped. This is exactly why layouts are worth modeling as routes: sidebars keep their scroll position, search boxes keep their text and animations do not restart.

Seeing the nesting

Nested routing is easy to picture once you can see the boxes. In the next stand-in every layout draws a labelled frame around its Outlet, so the URL's nesting becomes visible. There is also a checkbox that makes the middle layout forget its <Outlet />: that is the bug you will meet in real code.

Frames show the match chain

Open /account/orders/7: the page is four frames deep (root, account, orders, order detail), one per matched route. Now untick the box. The URL still matches the same four routes, but the Orders layout has no Outlet, so Order detail disappears. Nothing is wrong with the route config; the layout simply never said where its child goes. When a child route does not show up, check the nearest parent for <Outlet /> first.

Routes with no element

A parent route does not have to render anything of its own. A route that has a path but no element renders an <Outlet /> by default, so its children simply appear in place. That is handy for grouping URLs under a common prefix without adding any markup:

JSX
// App.jsx - React Router (read-only)
<Route path="reports">
  <Route path="sales" element={<Sales />} />
  <Route path="costs" element={<Costs />} />
</Route>

Here /reports/sales and /reports/costs exist, /reports alone does not (there is no index route), and no layout component was needed. Routes with a layout but no path are the next lesson: Layout Routes and Pathless Routes.

When to nest, and when not to

Nest when part of the screen is shared by several URLs and the URL structure matches the UI structure: an account area with tabs, a dashboard with a sidebar, a settings page with sections. Do not nest only because two URLs share a prefix and have nothing in common visually: the flat pattern path="users/:id/print" is fine on its own. And remember that nesting also decides what stays mounted: a component that must reset when the URL changes (a form for a different record) needs a key, such as the param value, or it will keep its old state. See Reconciliation and Keys in Depth.

Nested routes also set the stage for later chapters. In data mode every route in the chain can have its own loader, and all of them run in parallel before the page renders (see Loaders: Data Before Render). Links inside nested routes resolve relative to the route they appear in, which is the topic of Relative Links and Relative Routing. To share a value from a parent to its children without props, see Passing Data Down with Outlet Context.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Inside <Route path='users' element={<UsersLayout />}>, you add a child <Route path=':userId' element={<UserDetail />} />. At which URL does UserDetail render?

    Child paths are relative: the router joins the parent's path and the child's path, giving /users/:userId. UserDetail renders in the Outlet of UsersLayout.
  2. 2. The URL matches a parent route and a child route, but only the parent's content appears. What is the most likely cause?

    Children render where the parent places <Outlet />. Without it the match exists but has no slot, so the child never appears.
  3. 3. A user moves from /users to /users/42. What happens to AppLayout, the outermost layout?

    React sees the same component at the same position and keeps it mounted. Only the child route inside the Outlet changes, so counters, text inputs and scroll positions in the layout survive.
  4. 4. What does a route that has a path but no element render?

    When a route has no element, React Router renders an Outlet for it by default. That makes element-less routes a convenient way to group URLs under a prefix.

Summary

  • A route can have child routes; the URL is the parent's path plus the child's path, and child paths are written relative to the parent.
  • A parent renders <Outlet /> where its matching child should appear; forgetting it is the classic reason a child is missing.
  • A URL matches a whole chain of routes, and each route's element renders inside the previous one's Outlet.
  • Parent layouts stay mounted when only the child changes, so their state, scroll position and focus are kept.
  • A route without an element renders an Outlet by default, and index routes are the default child of a parent.
  • Use nesting when the UI is nested; use key where a component must reset for a new URL.

Next: Layout Routes and Pathless Routes