Skip to content

Commit c5396bd

Browse files
committed
Merge branch 'main' into release-next
2 parents 509dd49 + 4a910ac commit c5396bd

28 files changed

+606
-59
lines changed

.github/ISSUE_TEMPLATE/bug_report.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ body:
1111
- **All** bugs must have a **minimal** reproduction
1212
- Minimal means that it is not just pointing to a deployed site or a branch in your existing application
1313
- The preferred method is StackBlitz via [https://reactrouter.com/new](https://reactrouter.com/new)
14-
- If Stackblitz is not an option, a Github repo based on a fresh `create-react-router` app is acceptable
14+
- If Stackblitz is not an option, a GitHub repo based on a fresh `create-react-router` app is acceptable
1515
- Only in extraordinary circumstances will code snippets or maximal reproductions be accepted
1616
- Issue Review
1717
- Issues not meeting the above criteria will be closed and pointed to this document

.github/workflows/release.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,9 @@ jobs:
5151
# publish to npm.
5252
- name: 🚀 PR / Publish
5353
id: changesets
54-
uses: changesets/[email protected]
54+
# PLEASE KEEP THIS PINNED TO 1.4.10 to avoid a regression in 1.5.*
55+
# See https://github.com/changesets/action/issues/465
56+
uses: changesets/[email protected]
5557
with:
5658
version: pnpm run changeset:version
5759
commit: "chore: Update version for release"

GOVERNANCE.md

Lines changed: 32 additions & 32 deletions
Large diffs are not rendered by default.

contributors.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,7 @@
131131
- haivuw
132132
- hampelm
133133
- harshmangalam
134+
- HenriqueLimas
134135
- hernanif1
135136
- HK-SHAO
136137
- holynewbie
@@ -189,6 +190,7 @@
189190
- ken0x0a
190191
- kentcdodds
191192
- kettanaito
193+
- kilavvy
192194
- kiliman
193195
- kkirsche
194196
- kno-raziel
@@ -399,6 +401,7 @@
399401
- yracnet
400402
- ytori
401403
- yuleicul
404+
- zeevick10
402405
- zeromask1337
403406
- zheng-chuang
404407
- zxTomw

decisions/0003-data-strategy.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ We considered how to handle `shouldRevalidate` behavior. There's sort of 2 basic
141141

142142
I _think_ (1) is preferred to keep the API at a minimum and avoid leaking into _other_ ways to opt-out of revalidation. We already have an API for that so let's lean into it.
143143

144-
Additionally, another big con of (2) is that if we want to let them make revalidation decisions inside `dataStrategy` - we need to expose all of the informaiton required for that (`currentUrl`, `currentParams`, `nextUrl`, `nextParams`, `submission` info, `actionResult`, etc.) - the API becomes a mess.
144+
Additionally, another big con of (2) is that if we want to let them make revalidation decisions inside `dataStrategy` - we need to expose all of the information required for that (`currentUrl`, `currentParams`, `nextUrl`, `nextParams`, `submission` info, `actionResult`, etc.) - the API becomes a mess.
145145

146146
Therefore we are aiming to stick with one and let `shouldRevalidate` be the only way to opt-out of revalidation.
147147

decisions/0005-remixing-react-router.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,7 @@ function NewErrorBoundary() {
204204
const error = useRouteError();
205205

206206
if (error instanceof Response) {
207-
return <MyOldCatchBoudnary error={error} />;
207+
return <MyOldCatchBoundary error={error} />;
208208
} else {
209209
return <MyOldErrorBoundary error={error} />;
210210
}

docs/api/components/Await.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ via [useRouteError](../hooks/useRouteError) hook.
117117

118118
[modes: framework, data]
119119

120-
Takes a promise returned from a [LoaderFunction](../Other/LoaderFunction) value to be resolved and rendered.
120+
Takes a promise returned from a [LoaderFunction](https://api.reactrouter.com/v7/types/react_router.LoaderFunction.html) value to be resolved and rendered.
121121

122122
```jsx
123123
import { useLoaderData, Await } from "react-router";

docs/api/components/Link.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ This state is inaccessible on the server as it is implemented on top of [`histor
151151

152152
[modes: framework, data, declarative]
153153

154-
Can be a string or a partial [Path](../Other/Path):
154+
Can be a string or a partial [Path](https://api.reactrouter.com/v7/interfaces/react_router.Path.html):
155155

156156
```tsx
157157
<Link to="/some/path" />

docs/api/components/NavLink.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import { NavLink } from "react-router";
2020
<NavLink to="/message" />;
2121
```
2222

23-
States are available through the className, style, and children render props. See [NavLinkRenderProps](../Other/NavLinkRenderProps).
23+
States are available through the className, style, and children render props. See [NavLinkRenderProps](https://api.reactrouter.com/v7/types/react_router.NavLinkRenderProps).
2424

2525
```tsx
2626
<NavLink
@@ -233,7 +233,7 @@ Note that `pending` is only available with Framework and Data modes.
233233

234234
[modes: framework, data, declarative]
235235

236-
Can be a string or a partial [Path](../Other/Path):
236+
Can be a string or a partial [Path](https://api.reactrouter.com/v7/interfaces/react_router.Path):
237237

238238
```tsx
239239
<Link to="/some/path" />

docs/api/hooks/useBlocker.md

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Allow the application to block navigations within the SPA and present the user a
1515
## Signature
1616

1717
```tsx
18-
useBlocker(shouldBlock): Blocker
18+
useBlocker(shouldBlock: boolean | BlockerFunction): Blocker
1919
```
2020

2121
## Params
@@ -24,7 +24,43 @@ useBlocker(shouldBlock): Blocker
2424

2525
[modes: framework, data]
2626

27-
_No documentation_
27+
**boolean**
28+
29+
Whether or not the navigation should be blocked. If `true`, the blocker will prevent the navigation. If `false`, the blocker will not prevent the navigation.
30+
31+
[**BlockerFunction**](https://api.reactrouter.com/v7/types/react_router.BlockerFunction.html)
32+
33+
A function that returns a boolean indicating whether the navigation should be blocked.
34+
35+
```tsx
36+
const blocker = useBlocker(
37+
({ currentLocation, nextLocation, historyAction }) =>
38+
value !== "" &&
39+
currentLocation.pathname !== nextLocation.pathname
40+
);
41+
```
42+
43+
## Blocker
44+
45+
The [Blocker](https://api.reactrouter.com/v7/types/react_router.Blocker.html) object returned by the hook. It has the following properties:
46+
47+
### `state`
48+
49+
- `unblocked` - the blocker is idle and has not prevented any navigation
50+
- `blocked` - the blocker has prevented a navigation
51+
- `proceeding` - the blocker is proceeding through from a blocked navigation
52+
53+
### `location`
54+
55+
When in a `blocked` state, this represents the [`Location`](https://api.reactrouter.com/v7/interfaces/react_router.Location.html) to which we blocked a navigation. When in a `proceeding` state, this is the location being navigated to after a `blocker.proceed()` call.
56+
57+
### `proceed()`
58+
59+
When in a `blocked` state, you may call `blocker.proceed()` to proceed to the blocked location.
60+
61+
### `reset()`
62+
63+
When in a `blocked` state, you may call `blocker.reset()` to return the blocker back to an `unblocked` state and leave the user at the current location.
2864

2965
## Examples
3066

docs/api/hooks/useLoaderData.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ title: useLoaderData
1010

1111
[Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.useLoaderData.html)
1212

13-
Returns the data from the closest route [LoaderFunction](../Other/LoaderFunction) or [ClientLoaderFunction](../Other/ClientLoaderFunction).
13+
Returns the data from the closest route [LoaderFunction](https://api.reactrouter.com/v7/types/react_router.LoaderFunction.html) or [ClientLoaderFunction](https://api.reactrouter.com/v7/types/react_router.ClientLoaderFunction.html).
1414

1515
```tsx
1616
import { useLoaderData } from "react-router";

docs/api/hooks/useNavigate.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ function SomeComponent() {
2727
}
2828
```
2929

30-
It's often better to use [redirect](../utils/redirect) in [ActionFunction](../Other/ActionFunction) and [LoaderFunction](../Other/LoaderFunction) than this hook.
30+
It's often better to use [redirect](../utils/redirect) in [ActionFunction](https://api.reactrouter.com/v7/interfaces/react_router.ActionFunction.html) and [LoaderFunction](https://api.reactrouter.com/v7/types/react_router.LoaderFunction.html) than this hook.
3131

3232
## Signature
3333

docs/api/hooks/useResolvedPath.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ title: useResolvedPath
1010

1111
[Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.useResolvedPath.html)
1212

13-
Resolves the pathname of the given `to` value against the current location. Similar to [useHref](../hooks/useHref), but returns a [Path](../Other/Path) instead of a string.
13+
Resolves the pathname of the given `to` value against the current location. Similar to [useHref](../hooks/useHref), but returns a [Path](https://api.reactrouter.com/v7/interfaces/react_router.Path) instead of a string.
1414

1515
```tsx
1616
import { useResolvedPath } from "react-router";

docs/api/hooks/useRouteError.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ title: useRouteError
1010

1111
[Reference Documentation ↗](https://api.reactrouter.com/v7/functions/react_router.useRouteError.html)
1212

13-
Accesses the error thrown during an [ActionFunction](../Other/ActionFunction), [LoaderFunction](../Other/LoaderFunction), or component render to be used in a route module Error Boundary.
13+
Accesses the error thrown during an [ActionFunction](https://api.reactrouter.com/v7/interfaces/react_router.ActionFunction.html), [LoaderFunction](https://api.reactrouter.com/v7/types/react_router.LoaderFunction.html), or component render to be used in a route module Error Boundary.
1414

1515
```tsx
1616
export function ErrorBoundary() {

docs/explanation/concurrency.md

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Network Concurrency Management
3+
---
4+
5+
# Network Concurrency Management
6+
7+
[MODES: framework, data]
8+
9+
## Overview
10+
11+
When building web applications, managing network requests can be a daunting task. The challenges of ensuring up-to-date data and handling simultaneous requests often lead to complex logic in the application to deal with interruptions and race conditions. React Router simplifies this process by automating network management while mirroring and expanding upon the intuitive behavior of web browsers.
12+
13+
To help understand how React Router handles concurrency, it's important to remember that after `form` submissions, React Router will fetch fresh data from the `loader`s. This is called revalidation.
14+
15+
## Natural Alignment with Browser Behavior
16+
17+
React Router's handling of network concurrency is heavily inspired by the default behavior of web browsers when processing documents.
18+
19+
### Link Navigation
20+
21+
**Browser Behavior**: When you click on a link in a browser and then click on another before the page transition completes, the browser prioritizes the most recent `action`. It cancels the initial request, focusing solely on the latest link clicked.
22+
23+
**React Router Behavior**: React Router manages client-side navigation the same way. When a link is clicked within a React Router application, it initiates fetch requests for each `loader` tied to the target URL. If another navigation interrupts the initial navigation, React Router cancels the previous fetch requests, ensuring that only the latest requests proceed.
24+
25+
### Form Submission
26+
27+
**Browser Behavior**: If you initiate a form submission in a browser and then quickly submit another form again, the browser disregards the first submission, processing only the latest one.
28+
29+
**React Router Behavior**: React Router mimics this behavior when working with forms. If a form is submitted and another submission occurs before the first completes, React Router cancels the original fetch requests. It then waits for the latest submission to complete before triggering page revalidation again.
30+
31+
## Concurrent Submissions and Revalidation
32+
33+
While standard browsers are limited to one request at a time for navigations and form submissions, React Router elevates this behavior. Unlike navigation, with [`useFetcher`][use_fetcher] multiple requests can be in flight simultaneously.
34+
35+
React Router is designed to handle multiple form submissions to server `action`s and concurrent revalidation requests efficiently. It ensures that as soon as new data is available, the state is updated promptly. However, React Router also safeguards against potential pitfalls by refraining from committing stale data when other `action`s introduce race conditions.
36+
37+
For instance, if three form submissions are in progress, and one completes, React Router updates the UI with that data immediately without waiting for the other two so that the UI remains responsive and dynamic. As the remaining submissions finalize, React Router continues to update the UI, ensuring that the most recent data is displayed.
38+
39+
Using this key:
40+
41+
- `|`: Submission begins
42+
- ✓: Action complete, data revalidation begins
43+
- ✅: Revalidated data is committed to the UI
44+
- ❌: Request cancelled
45+
46+
We can visualize this scenario in the following diagram:
47+
48+
```text
49+
submission 1: |----✓-----✅
50+
submission 2: |-----✓-----✅
51+
submission 3: |-----✓-----✅
52+
```
53+
54+
However, if a subsequent submission's revalidation completes before an earlier one, React Router discards the earlier data, ensuring that only the most up-to-date information is reflected in the UI:
55+
56+
```text
57+
submission 1: |----✓---------❌
58+
submission 2: |-----✓-----✅
59+
submission 3: |-----✓-----✅
60+
```
61+
62+
Because the revalidation from submission (2) started later and landed earlier than submission (1), the requests from submission (1) are canceled and only the data from submission (2) is committed to the UI. It was requested later, so it's more likely to contain the updated values from both (1) and (2).
63+
64+
## Potential for Stale Data
65+
66+
It's unlikely your users will ever experience this, but there are still chances for the user to see stale data in very rare conditions with inconsistent infrastructure. Even though React Router cancels requests for stale data, they will still end up making it to the server. Canceling a request in the browser simply releases browser resources for that request; it can't "catch up" and stop it from getting to the server. In extremely rare conditions, a canceled request may change data after the interrupting `action`'s revalidation lands. Consider this diagram:
67+
68+
```text
69+
👇 interruption with new submission
70+
|----❌----------------------✓
71+
|-------✓-----✅
72+
👆
73+
initial request reaches the server
74+
after the interrupting submission
75+
has completed revalidation
76+
```
77+
78+
The user is now looking at different data than what is on the server. Note that this problem is both extremely rare and exists with default browser behavior, too. The chance of the initial request reaching the server later than both the submission and revalidation of the second is unexpected on any network and server infrastructure. If this is a concern with your infrastructure, you can send timestamps with your form submissions and write server logic to ignore stale submissions.
79+
80+
## Example
81+
82+
In UI components like comboboxes, each keystroke can trigger a network request. Managing such rapid, consecutive requests can be tricky, especially when ensuring that the displayed results match the most recent query. However, with React Router, this challenge is automatically handled, ensuring that users see the correct results without developers having to micromanage the network.
83+
84+
```tsx filename=app/pages/city-search.tsx
85+
export async function loader({ request }) {
86+
const { searchParams } = new URL(request.url);
87+
const cities = await searchCities(searchParams.get("q"));
88+
return cities;
89+
}
90+
91+
export function CitySearchCombobox() {
92+
const fetcher = useFetcher<typeof loader>();
93+
94+
return (
95+
<fetcher.Form action="/city-search">
96+
<Combobox aria-label="Cities">
97+
<ComboboxInput
98+
name="q"
99+
onChange={(event) =>
100+
// submit the form onChange to get the list of cities
101+
fetcher.submit(event.target.form)
102+
}
103+
/>
104+
105+
{/* render with the loader's data */}
106+
{fetcher.data ? (
107+
<ComboboxPopover className="shadow-popup">
108+
{fetcher.data.length > 0 ? (
109+
<ComboboxList>
110+
{fetcher.data.map((city) => (
111+
<ComboboxOption
112+
key={city.id}
113+
value={city.name}
114+
/>
115+
))}
116+
</ComboboxList>
117+
) : (
118+
<span>No results found</span>
119+
)}
120+
</ComboboxPopover>
121+
) : null}
122+
</Combobox>
123+
</fetcher.Form>
124+
);
125+
}
126+
```
127+
128+
All the application needs to know is how to query the data and how to render it. React Router handles the network.
129+
130+
## Conclusion
131+
132+
React Router offers developers an intuitive, browser-based approach to managing network requests. By mirroring browser behaviors and enhancing them where needed, it simplifies the complexities of concurrency, revalidation, and potential race conditions. Whether you're building a simple webpage or a sophisticated web application, React Router ensures that your user interactions are smooth, reliable, and always up to date.
133+
134+
[use_fetcher]: ../api/hooks/useFetcher

docs/how-to/accessibility.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Accessibility
3+
---
4+
5+
# Accessibility
6+
7+
Accessibility in a React Router app looks a lot like accessibility on the web in general. Using proper semantic markup and following the [Web Content Accessibility Guidelines (WCAG)][wcag] will get you most of the way there.
8+
9+
React Router makes certain accessibility practices the default where possible and provides APIs to help where it's not.
10+
11+
## Links
12+
13+
The [`<Link>` component][link] renders a standard anchor tag, meaning that you get its accessibility behaviors from the browser for free!
14+
15+
React Router also provides the [`<NavLink/>`][navlink] which behaves the same as `<Link>`, but it also provides context for assistive technology when the link points to the current page. This is useful for building navigation menus or breadcrumbs.
16+
17+
## Routing
18+
19+
If you are rendering [`<Scripts>`][scripts] in your app, there are some important things to consider to make client-side routing more accessible for your users.
20+
21+
With a traditional multi-page website we don't have to think about route changes too much. Your app renders an anchor tag, and the browser handles the rest. If your users disable JavaScript, your React Router app should already work this way by default!
22+
23+
When the client scripts in React Router are loaded, React Router takes control of routing and prevents the browser's default behavior. React Router doesn't make any assumptions about your UI as the route changes. There are some important features you'll want to consider as a result, including:
24+
25+
- **Focus management:** What element receives focus when the route changes? This is important for keyboard users and can be helpful for screen-reader users.
26+
- **Live-region announcements:** Screen-reader users also benefit from announcements when a route has changed. You may want to also notify them during certain transition states depending on the nature of the change and how long loading is expected to take.
27+
28+
In 2019, [Marcy Sutton led and published findings from user research][marcy-sutton-led-and-published-findings-from-user-research] to help developers build accessible client-side routing experiences.
29+
30+
[link]: ../api/components/Link
31+
[navlink]: ../api/components/NavLink
32+
[scripts]: ../api/components/Scripts
33+
[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/
34+
[marcy-sutton-led-and-published-findings-from-user-research]: https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing

0 commit comments

Comments
 (0)