|
| 1 | +<title>useMatch</title> |
| 2 | + |
| 3 | +##### `useMatch` gives you a reactive object describing the URL the user is visiting |
| 4 | + |
| 5 | +<div class="text-xl"> |
| 6 | + |
| 7 | +</div> |
| 8 | + |
| 9 | +- [Usage](#usage) |
| 10 | + |
| 11 | + - [Reading the current URL (location) in a reactive context](#accessing-id-param-for-route-users-id) |
| 12 | + |
| 13 | +- [Reference](#reference) |
| 14 | + |
| 15 | + - [`useMatch()`](#hello-world) |
| 16 | + |
| 17 | +- [Troublehooting](#troublehooting) |
| 18 | + |
| 19 | +--- |
| 20 | + |
| 21 | +## Usage |
| 22 | + |
| 23 | +Route params are an important part of the routing system. They allow you to access the dynamic parts of the URL, based on the currently matching [`Route`](/api/router/route). |
| 24 | + |
| 25 | +### Reading `id` param for route `/users/:id` |
| 26 | + |
| 27 | +In our router config, we will usually have a few `Route`'s with dynamic parts. For example, take this router config which has a `Route` with path `/users/:id`. |
| 28 | + |
| 29 | +```tsx twoslash {6} |
| 30 | +import { Router, Route } from "@solidjs/router"; |
| 31 | + |
| 32 | +export function App() { |
| 33 | + return ( |
| 34 | + <Router> |
| 35 | + <Route path="/users/:id" /> |
| 36 | + </Router> |
| 37 | + ); |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +To access the `:id` part of the route, call `useParams()` inside a component. The returned object `params` will have a field `id` that will match the `:id` part of the URL. For example, if the URL is `/users/123`, then `params.id` will be `123`. |
| 42 | + |
| 43 | +```tsx twoslash {4-8} |
| 44 | +// @errors: 2571 |
| 45 | +// @lib: ES2015 |
| 46 | +import { useParams } from "@solidjs/router"; |
| 47 | + |
| 48 | +function User() { |
| 49 | + const params = useParams<{ id: string }>(); |
| 50 | + |
| 51 | + // when url is /users/123 |
| 52 | + console.log(params.id); |
| 53 | + // 123 |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +### Reading both `id` and `project` params for route `/users/:id/projects/:project` |
| 58 | + |
| 59 | +We could also have a `Route` with with multiple dynamic parts. For example, a route with path `/users/:id/projects/:project`. In this case, we would have two params: `id` and `project`. |
| 60 | + |
| 61 | +```tsx twoslash {6-8,14-18} |
| 62 | +// @errors: 2571 |
| 63 | +// @lib: ES2015 |
| 64 | +import { Router, Route, useParams } from "@solidjs/router"; |
| 65 | + |
| 66 | +export function App() { |
| 67 | + return ( |
| 68 | + <Router> |
| 69 | + <Route path="/users/:id"> |
| 70 | + <Route path="/projects/:project" /> |
| 71 | + </Route> |
| 72 | + </Router> |
| 73 | + ); |
| 74 | +} |
| 75 | + |
| 76 | +function User() { |
| 77 | + const params = useParams<{ id: string; project: string }>(); |
| 78 | + |
| 79 | + // when url is /users/123/projects/hello-world |
| 80 | + console.log(params.id, params.project); |
| 81 | + // 123, hello-world |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +### Fetch data based on the path params |
| 86 | + |
| 87 | +The route path parameters are usually used to fetch data from the server based on the current route. For the best user experience with parallel loading of data and route code, you should fetch the data in the the `Route`'s data function. The data function is passed the `params` object as an argument. |
| 88 | + |
| 89 | +In some cases, you might want to create async resources within your component tree, outside the `routeData` function. Here, you would need to get the params from the `useParams` hook. |
| 90 | + |
| 91 | +For example, if you have a route like `/users/:id`, then you can access the `id` param by using `useParams` inside your component. |
| 92 | + |
| 93 | +```tsx twoslash {2} |
| 94 | +// @errors: 2571 |
| 95 | +// @lib: ES2015 |
| 96 | +import { useParams, Router, Route } from "@solidjs/router"; |
| 97 | +import { createResource, JSX } from "solid-js"; |
| 98 | + |
| 99 | +async function fetchUser(id: string): Promise<{ name: string }> { |
| 100 | + return { name: "John" }; |
| 101 | +} |
| 102 | + |
| 103 | +// ---cut--- |
| 104 | +function User() { |
| 105 | + const params = useParams<{ id: string }>(); |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +Then, you can use the `id` param as the source for your resource. You can fetch data for the user with the matching `id`. For example, here we fetch and render the user's name in your component based on the `id` param. |
| 110 | + |
| 111 | +```tsx twoslash {4-7} |
| 112 | +// @errors: 2571 |
| 113 | +// @lib: ES2015 |
| 114 | +import { useParams, Router, Route } from "@solidjs/router"; |
| 115 | +import { createResource, JSX } from "solid-js"; |
| 116 | + |
| 117 | +async function fetchUser(id: string): Promise<{ name: string }> { |
| 118 | + return { name: "John" }; |
| 119 | +} |
| 120 | + |
| 121 | +// ---cut--- |
| 122 | +function User() { |
| 123 | + const params = useParams<{ id: string }>(); |
| 124 | + |
| 125 | + // fetch user based on the id path parameter |
| 126 | + const [user] = createResource(() => params.id, fetchUser); |
| 127 | + |
| 128 | + return <div>{user()?.name}</div>; |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +--- |
| 133 | + |
| 134 | +## Reference |
| 135 | + |
| 136 | +### `useMatch()` |
| 137 | + |
| 138 | +Call `useMatch()` inside a component to get the current URL (location). |
| 139 | + |
| 140 | +#### Returns |
| 141 | + |
| 142 | +A reactive object containing the attributes of the URL. The fields of the object are the names of the dynamic parts of the route path. For example, |
| 143 | + |
| 144 | +- `pathname: string`: the pathname part of the URL, without the query string, |
| 145 | +- `search: string`: the query string part of the URL |
| 146 | +- `hash: string` |
0 commit comments