Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(components/link): add missing information to Relative section #12142

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 23 additions & 4 deletions docs/components/link.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,28 @@ A relative `<Link to>` value (that does not begin with `/`) resolves relative to

## `relative`

By default, links are relative to the route hierarchy (`relative="route"`), so `..` will go up one `Route` level from the current contextual route. Occasionally, you may find that you have matching URL patterns that do not make sense to be nested, and you'd prefer to use relative _path_ routing from the current contextual route path. You can opt into this behavior with `relative="path"`:
By default, links are relative to the route hierarchy (`relative="route"`), so `..` will go up one `Route` level from the current contextual route. However, `index` routes (or any other routes that don't add to the path) are skipped.

```jsx
```tsx
<Route path="main">
<Route index element={<Main />} />
<Route path="module">
<Route index element={<FeatureA />} />
<Route path="feature-a" element={<FeatureA />} />
<Route path="feature-b" element={<FeatureB />} />
</Route>
</Route>;

function FeatureA() {
return <Link to="..">Back</Link>;
}
```

Let's assume the current path is `/main/module`. When you click the "Back" link, it navigates one level up in the route hierarchy, skipping routes such as `index` that don't add to the path. As a result, the path becomes `/main`. Now, let's assume the current path is `/main/module/feature-a`. When you click the "Back" link, the path becomes `/main/module`.

Occasionally, you may find that you have matching URL patterns that do not make sense to be nested, and you'd prefer to use relative _path_ routing from the current contextual route path. You can opt into this behavior with `relative="path"`:

```tsx
// Contact and EditContact do not share additional UI layout
<Route path="/" element={<Layout />}>
<Route path="contacts/:id" element={<Contact />} />
Expand All @@ -91,11 +110,11 @@ function EditContact() {
}
```

Please note that `relative: "path"` only impacts the resolution of a relative path. It does not change the "starting" location for that relative path resolution. This resolution is always relative to the current location in the Route hierarchy (i.e., the route `Link` is rendered in).
Please note that `relative="path"` only impacts the resolution of a relative path. It does not change the "starting" location for that relative path resolution. This resolution is always relative to the current location in the Route hierarchy (i.e., the route `Link` is rendered in).

If you wish to use path-relative routing against the current URL instead of the route hierarchy, you can do that with the current [`location`][use-location] and the `URL` constructor (note the trailing slash behavior):

```js
```ts
// Assume the current URL is https://remix.run/docs/en/main/start/quickstart
let location = useLocation();

Expand Down