Skip to content

Commit 4c4e735

Browse files
LadyBluenotesLadyBluenotes
committed
router, preload, useSubmission, useSubmissions
1 parent 260ca79 commit 4c4e735

4 files changed

Lines changed: 192 additions & 49 deletions

File tree

‎src/routes/solid-router/reference/components/router.mdx‎

Lines changed: 116 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,122 @@ description: >-
1616
context and configuration for all child routes and navigation.
1717
---
1818

19-
The `Router` component is a top level component that manages the routing of your application.
20-
There is an optional `root` prop that can be used to wrap the entire application in a layout component, which will not be updated when the page changes.
19+
`Router` is the top-level component that manages routing for the application.
20+
It provides the routing context used by route matching, navigation, link interception, and route preloading.
21+
22+
## Import
23+
24+
```tsx
25+
import { Router } from "@solidjs/router";
26+
```
27+
28+
## Type
29+
30+
```tsx
31+
type RouterProps = BaseRouterProps & {
32+
url?: string;
33+
actionBase?: string;
34+
explicitLinks?: boolean;
35+
preload?: boolean;
36+
};
37+
38+
type BaseRouterProps = {
39+
base?: string;
40+
root?: Component<RouteSectionProps>;
41+
rootPreload?: RoutePreloadFunc;
42+
singleFlight?: boolean;
43+
children?: JSX.Element | RouteDefinition | RouteDefinition[];
44+
transformUrl?: (url: string) => string;
45+
/* @deprecated use rootPreload */
46+
rootLoad?: RoutePreloadFunc;
47+
};
48+
```
49+
50+
## Props
51+
52+
### `base`
53+
54+
- **Type:** `string`
55+
- **Optional:** Yes
56+
57+
Base URL used for route matching and path resolution.
58+
59+
### `root`
60+
61+
- **Type:** `Component<RouteSectionProps>`
62+
- **Optional:** Yes
63+
64+
Layout component that wraps the matched route and stays mounted while the matched route subtree changes. It receives `params`, `location`, `data`, and `children` through `RouteSectionProps`.
65+
66+
### `rootPreload`
67+
68+
- **Type:** `RoutePreloadFunc`
69+
- **Optional:** Yes
70+
71+
Preload function for the root route context. Its return value is passed to the `root` component through the `data` field in `RouteSectionProps`.
72+
73+
### `singleFlight`
74+
75+
- **Type:** `boolean`
76+
- **Default:** `true`
77+
- **Optional:** Yes
78+
79+
Enables or disables single-flight handling for actions. This only affects actions that support `withOptions`.
80+
81+
### `children`
82+
83+
- **Type:** `JSX.Element | RouteDefinition | RouteDefinition[]`
84+
- **Optional:** Yes
85+
86+
Route definitions.
87+
88+
### `transformUrl`
89+
90+
- **Type:** `(url: string) => string`
91+
- **Optional:** Yes
92+
93+
Transforms the pathname before route matching and anchor preloading.
94+
95+
### `rootLoad`
96+
97+
- **Type:** `RoutePreloadFunc`
98+
- **Optional:** Yes
99+
100+
Deprecated alias for `rootPreload`.
101+
102+
### `actionBase`
103+
104+
- **Type:** `string`
105+
- **Default:** `"/_server"`
106+
- **Optional:** Yes
107+
108+
Base path for intercepted action form submissions. Only `POST` forms whose normalized action path starts with this base are intercepted.
109+
110+
### `explicitLinks`
111+
112+
- **Type:** `boolean`
113+
- **Default:** `false`
114+
- **Optional:** Yes
115+
116+
When `true`, only anchors marked with the `link` attribute are intercepted. When `false`, matching same-origin anchors are intercepted automatically.
117+
118+
### `preload`
119+
120+
- **Type:** `boolean`
121+
- **Default:** `true`
122+
- **Optional:** Yes
123+
124+
Enables or disables link and focus-based route preloading. When enabled, preloading is triggered from mouse move, focus, and touchstart on intercepted anchors.
125+
126+
## Behavior
127+
128+
- On the server, `Router` delegates to `StaticRouter`, which is the only path where `url` is used.
129+
- On the client, `Router` reads from and writes to the browser history using the current `pathname`, `search`, and `hash`.
130+
- When navigation writes history state, `Router` preserves the internal history depth metadata used by blocked back and forward navigation.
131+
- `rootLoad` is still supported and is used as a fallback when `rootPreload` is not provided.
132+
- Link interception, route preloading, and action form interception are handled through delegated document-level event listeners.
133+
134+
## Examples
21135

22136
```tsx
23137
import { render } from "solid-js/web";
@@ -35,13 +149,3 @@ render(
35149
document.getElementById("root")
36150
);
37151
```
38-
39-
| prop | type | description |
40-
| ------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41-
| children | `JSX.Element`, `RouteDefinition`, or `RouteDefinition[]` | The route definitions |
42-
| root | Component | Top level layout component |
43-
| base | string | Base url to use for matching routes |
44-
| actionBase | string | Root url for server actions, default: `/_server` |
45-
| preload | boolean | Enables/disables preloads globally, default: `true` |
46-
| explicitLinks | boolean | Disables all anchors being intercepted and instead requires `<A>`. default: `false`. (To disable interception for a specific link, set `target` to any value, e.g. `<a target="_self">`.) |
47-
| url | string | The initial route to render |

‎src/routes/solid-router/reference/data-apis/use-submission.mdx‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ description: >-
1616
optimistic updates, and errors for single forms.
1717
---
1818

19-
The `useSubmission` primitive returns the state of the _most recent_ submission for a given [action](/solid-router/concepts/actions).
19+
`useSubmission` returns the most recent tracked submission for an [action](/solid-router/concepts/actions).
2020

2121
## Import
2222

@@ -47,38 +47,57 @@ The action to track.
4747
- **Type:** `(input: V) => boolean`
4848
- **Required:** No
4949

50-
A function that filters submissions.
51-
It is executed for each submission in the order of creation.
52-
It receives an array of the action's inputs as a parameter and must return `true` to select the submission or `false` otherwise.
53-
The first submission that passes the filter is returned by `useSubmission`.
50+
A function that receives the action input and returns `true` for matching submissions.
5451

5552
## Return value
5653

5754
`useSubmission` returns a reactive object with the following properties:
5855

5956
### `input`
6057

61-
A reactive value representing the input data of the action.
58+
- **Type:** `T | undefined`
59+
- **Defined when:** A matching submission exists.
60+
61+
Reactive input data for the submission.
6262

6363
### `result`
6464

65-
A reactive value representing the successful return value of the action.
65+
- **Type:** `NarrowResponse<U> | undefined`
66+
- **Defined when:** The submission completes successfully.
67+
68+
Reactive successful return value for the submission.
6669

6770
### `error`
6871

69-
A reactive value representing any error thrown by the action.
72+
- **Type:** `any`
73+
- **Defined when:** The submission throws or rejects.
74+
75+
Reactive error value for the submission.
7076

7177
### `pending`
7278

73-
A reactive boolean indicating if the action is currently running.
79+
- **Type:** `boolean | undefined`
80+
- **Defined when:** A matching submission exists.
81+
82+
Whether the submission is still running.
7483

7584
### `clear`
7685

77-
A function to clear the submission's state.
86+
- **Type:** `() => void`
87+
88+
Clears the submission state.
7889

7990
### `retry`
8091

81-
A function to re-execute the submission with the same input.
92+
- **Type:** `() => void`
93+
94+
Re-executes the submission with the same input.
95+
96+
## Behavior
97+
98+
- `useSubmission` reads from the router's tracked submissions for the given action.
99+
- If a `filter` is provided, it returns the most recent submission whose input matches the filter.
100+
- If there is no matching submission, it returns a stub with `undefined` data fields and no-op `clear` and `retry` methods.
82101

83102
## Examples
84103

‎src/routes/solid-router/reference/data-apis/use-submissions.mdx‎

Lines changed: 29 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ description: >-
1616
history, handle errors, and show optimistic updates.
1717
---
1818

19-
The `useSubmissions` primitive returns the state of all submissions for a given [action](/solid-router/concepts/actions).
19+
`useSubmissions` returns the state of all tracked submissions for an [action](/solid-router/concepts/actions).
2020

2121
## Import
2222

@@ -49,9 +49,8 @@ The action to track.
4949
- **Type:** `(input: V) => boolean`
5050
- **Required:** No
5151

52-
A function that filters submissions.
53-
It is executed for each submission in the order of creation.
54-
It receives an array of the action's inputs as a parameter and must return `true` to select the submission or `false` otherwise.
52+
A function that receives the action input and returns `true` for matching submissions.
53+
Only matching submissions are included in the returned array.
5554

5655
## Return value
5756

@@ -60,27 +59,47 @@ Each submission object has the following properties:
6059

6160
### `input`
6261

63-
The reactive input data of the action.
62+
- **Type:** `T`
63+
64+
Reactive input data for the submission.
6465

6566
### `result`
6667

67-
A reactive value representing the successful return value of the action.
68+
- **Type:** `NarrowResponse<U> | undefined`
69+
- **Defined when:** The submission completes successfully.
70+
71+
Reactive successful return value for the submission.
6872

6973
### `error`
7074

71-
A reactive value for any error thrown by the action.
75+
- **Type:** `any`
76+
- **Defined when:** The submission throws or rejects.
77+
78+
Reactive error value for the submission.
7279

7380
### `pending`
7481

75-
A reactive boolean indicating if the action is currently running.
82+
- **Type:** `boolean`
83+
84+
Whether the submission is still running.
7685

7786
### `clear`
7887

79-
A function to clear the submission's state.
88+
- **Type:** `() => void`
89+
90+
Clears the submission state.
8091

8192
### `retry`
8293

83-
A function to re-execute the submission with the same input.
94+
- **Type:** `() => void`
95+
96+
Re-executes the submission with the same input.
97+
98+
## Behavior
99+
100+
- `useSubmissions` returns a reactive array backed by the router's tracked submissions for the given action.
101+
- If a `filter` is provided, only submissions whose input matches the filter are included.
102+
- The returned array also exposes a `pending` property that is `true` when any included submission does not yet have a result.
84103

85104
## Examples
86105

‎src/routes/solid-router/reference/preload-functions/preload.mdx‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,7 @@ description: >-
1616
prefetching for instant page transitions.
1717
---
1818

19-
The `preload` function is a property on a route definition that initiates data fetching before a user navigates to the route.
20-
21-
`preload` runs in two separate phases:
22-
23-
- **Preload phase:**
24-
Triggered by user intent (e.g., hovering over a link), the function is called to initiate data fetching.
25-
- **Rendering phase:**
26-
Triggered by actual navigation, the function is called a second time to provide the fetched data to the component.
19+
`preload` is a route-definition property that runs during route preloading and rendering.
2720

2821
## Import
2922

@@ -65,19 +58,27 @@ It corresponds to the value returned by the [`useLocation` primitive](/solid-rou
6558

6659
A string indicating the context in which the function is called.
6760

68-
- `"preload"`:
69-
The function is running to initiate data fetching.
70-
- `"navigate"`:
71-
The function is running during navigation to the route.
72-
- `"initial"`:
73-
The function is running for the first route on page load.
61+
| Value | Meaning |
62+
| ---------- | ------------------------------------------------------------------ |
63+
| `preload` | Preloading route code or data. |
64+
| `navigate` | Client navigation to the route. |
65+
| `native` | Native history navigation, such as back or forward. |
66+
| `initial` | The first render for the current request or page load. |
7467

7568
## Return value
7669

7770
The value returned by `preload` is passed to the route's component as the `data` prop.
7871

79-
- In the **preload phase** (`intent: "preload"`), the return value is **ignored**.
80-
- In the **rendering phase** (`intent: "navigate"` or `"initial"`), the return value is **captured** and provided to the component.
72+
| Intent | Return value behavior |
73+
| ----------------------------------- | --------------------------------------------- |
74+
| `preload` | Ignored. |
75+
| `initial`, `navigate`, or `native` | Captured and passed to the component as `data`. |
76+
77+
## Behavior
78+
79+
- During route preloading, the router calls `preload` for each matched route.
80+
- `load` is a deprecated alias for `preload` on route definitions.
81+
- Route component preloads run before the route's `preload` function when the component exposes a `.preload()` method.
8182

8283
## Examples
8384

0 commit comments

Comments
 (0)