Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 50 ยท Nested Routes and Layouts

Relative Links and Relative Routing

Learn how React Router resolves relative links: route-relative versus path-relative, what '..' really means, and the pitfalls in nested layouts.

Once your routes are nested, you stop wanting to write full URLs everywhere. A page inside /projects/7 should be able to link to tasks/2 without knowing that the project id is 7, and a "Back" link should work no matter where the whole feature is mounted. React Router supports this with relative links: any to value that does not start with a slash is resolved against something. The interesting question is against what.

The answer surprises many people. By default a relative link is resolved against the route hierarchy, not against the URL you see in the address bar. That is why .. means "go up one route", which is not always "remove one URL segment". This lesson explains both modes, shows where they differ, and lists the traps. It builds on Nested Routes and Outlet and Layout Routes and Pathless Routes.

As in the other lessons, the real React Router code is shown read-only. The runnable examples use a small hand-written router (the part above the "Lesson code" comment), which copies React Router's resolution rules for this topic so you can see them work.

Absolute and relative values

A to value that starts with / is absolute: it means exactly that path and never depends on where the link is rendered. Everything else is relative:

JSX
import { Link } from "react-router";

// Rendered by the route whose full path is /projects/7
<Link to="/projects">All projects</Link>   // absolute  -> /projects
<Link to="tasks/2">Task 2</Link>           // relative  -> /projects/7/tasks/2
<Link to="">This project</Link>            // relative  -> /projects/7
<Link to="..">All projects</Link>          // relative  -> /projects

Use absolute paths for destinations that never move (the home page, the login page) and relative paths for links inside one feature. Relative links make a feature portable: mount the same projects routes under /admin/projects and every internal link still works.

The same rules apply wherever you can give React Router a destination: <Link to>, <Navigate to>, navigate("..") from useNavigate, and useResolvedPath(".."). A value that is only a query string (to="?sort=price") or only a hash (to="#details") keeps the current path and changes the rest.

Route-relative: the default

When you write <Link to="..">, React Router looks at the chain of routes that were matched for the component that renders the link, and treats each route as one step. Every route in that chain has a base pathname: the part of the URL that route consumed, including its parents.

For the URL /projects/7/tasks/3, with nested routes projects, then :projectId, then tasks/:taskId, the chain looks like this:

flowchart TD
  A["root route<br/>base: /"] --> B["projects<br/>base: /projects"]
  B --> C[":projectId<br/>base: /projects/7"]
  C --> D["tasks/:taskId<br/>base: /projects/7/tasks/3"]

Each matched route has a base pathname; route-relative links start from one of these.

A relative link starts at the route that renders it. Each leading .. moves one route up the chain. Whatever is left of the to value is then appended like an ordinary path.

Notice the last route: tasks/:taskId is one route that happens to consume two URL segments. So .. from the task page jumps over both of them and lands on /projects/7, not on /projects/7/tasks. If you had written tasks and :taskId as two nested routes instead, .. would behave differently. The route tree, not the string, decides.

Three rules complete the picture:

  • A link resolves relative to the route of the component that renders it. A <Link to="tasks/1"> inside the project layout always points at /projects/<id>/tasks/1, even when the URL is currently /projects/7/tasks/3, because the layout's route ends at /projects/7.
  • Index routes are not a step. A link inside an index route resolves from its parent route, which has the same URL anyway.
  • Pathless layout routes (routes with no path) are not a step either. Wrapping routes in a layout never changes where .. goes.

Path-relative: relative="path"

Sometimes you really do want "remove the last URL segment". Add relative="path" and React Router ignores the route tree: it starts from the full current URL path, and each .. removes one segment.

JSX
// Rendered by the route tasks/:taskId at /projects/7/tasks/3
<Link to="..">Project</Link>                       // route: /projects/7
<Link to=".." relative="path">Task list</Link>     // path:  /projects/7/tasks
<Link to="../4" relative="path">Next task</Link>   // path:  /projects/7/tasks/4

Path-relative links are the natural tool for siblings that share a parent segment, such as "next task" or "previous page". They are also how plain HTML relative URLs behave, so they are the least surprising for people coming from <a href="../4">.

flowchart LR
  T["Task page<br/>/projects/7/tasks/3"]
  T -->|"to='..' (route)"| P["/projects/7"]
  T -->|"to='..' relative='path'"| L["/projects/7/tasks"]

The same .. leads to different places depending on the mode.

Splat routes (path="docs/*") deserve a mention. A splat route is still one route, and the splat part is not part of its own base path. So .. inside it leaves the whole route, and you need relative="path" to climb through the individual segments that the splat swallowed.

See the resolution happen

The first example is a "link lab". The component is mounted at three places in the route tree, and it prints how each to value resolves in both modes, using the same algorithm as above: the route chain, with index routes and pathless routes skipped.

Route-relative versus path-relative

Open /projects/7/tasks/3 first. The chain has four routes, and the two columns disagree on .., ../.. and ../edit, because the last route consumed two segments. Then open /projects/7: the chain is shorter (the index route does not count) and both columns agree, since every route in that chain consumed exactly one segment. The rule of thumb: the modes only differ when some route consumes more or fewer than one segment.

The second example puts real links into a layout and a leaf. Each link prints the target it resolved to, so you can check it against the address bar.

Links in a layout and in a leaf

Go to project 7, task 2. The layout's links all start with /projects/7, regardless of the task in the URL, because the layout's route is projects/:projectId. "Back to project" is route-relative and lands on /projects/7, "Task list" is path-relative and lands on /projects/7/tasks, and "Task 4" is a sibling link that only works with relative="path". Now jump to project 9: every link updates, because relative links are re-resolved from the current params. Nothing is hard-coded.

This time the project route is written as projects/:projectId, one route with two segments. Compare it with the nested version in the first example: there, .. from the project layout would stop at /projects; here "Up one route" leaves the whole projects/:projectId route and lands on /. That is why "All projects" uses an absolute path. Two route trees that match the same URLs can resolve .. differently. This is the trap behind most "my relative link goes to the wrong place" bugs.

Pitfalls and good habits

  • Links resolve from the component that renders them. If you move a link component into a different part of the route tree, its relative targets move with it. Test links after refactoring layouts.
  • Count routes, not slashes. Before writing .., look at the route definitions. A route with a path like tasks/:taskId is one step. When you want "one URL segment up", say so with relative="path".
  • Don't mix up .. and "go back". .. builds a URL for a parent. It does not return the user to the page they came from; that is navigate(-1) or a stored return location (see useLocation and Navigation State).
  • Prefer absolute paths for fixed destinations (/login, /), and relative paths for links inside a feature that could be mounted elsewhere.
  • Reaching above the root stops at /. Extra .. segments do not fail; they land on the root.
  • Keep an eye on the real URL. The router leaves the address bar as the source of truth, so a quick look at where a link points (hover shows it) catches most mistakes.

When a relative link is hard to reason about, call useResolvedPath(to) (or useResolvedPath(to, { relative: "path" })) in the component and log the result. In the live demos above, useResolvedPath is the function doing exactly that.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In the default route-relative mode, what does a leading .. in to mean?

    Each leading .. moves one route up the matched route chain. A route that consumes two URL segments counts as a single step, so this is not the same as removing one segment.
  2. 2. A route is defined as path="tasks/:taskId" (one route). A link inside it at /projects/7/tasks/3 uses to=".." with relative="path". Where does it go?

    relative="path" ignores the route tree and removes exactly one URL segment from /projects/7/tasks/3, which gives /projects/7/tasks. Without it, the link would go to the parent route, /projects/7.
  3. 3. A <Link to="tasks/1"> is rendered by a project layout route at /projects/7. The URL is /projects/7/tasks/3. Where does the link point?

    A relative link resolves from the route of the component that renders it. The layout's route ends at /projects/7, so the target is /projects/7/tasks/1, whatever the current URL is.
  4. 4. Which routes are NOT counted as a step when React Router resolves ..?

    Index routes and pathless (layout) routes add nothing to the URL, so they are skipped. Dynamic segments and routes with an Outlet are ordinary steps.

Summary

  • A to value that starts with / is absolute; anything else is relative and is resolved from where the link is rendered.
  • By default, resolution is route-relative: each leading .. climbs one route in the matched chain, and a route that consumes several segments still counts as one step.
  • relative="path" switches to path-relative resolution: start from the full URL path and let .. remove one segment at a time. Use it for siblings such as "next task".
  • Index routes and pathless layout routes are not steps; a link resolves from the route of the component that renders it, not from the deepest match.
  • The same rules apply to Link, Navigate, useNavigate, and useResolvedPath.
  • Count routes before you write .., and use useResolvedPath to check what a link will do.

Next: Dynamic Segments and useParams