Skip to main content
Version: Next

wasp/client/router

Type-safe links and URLs for the routes you declare in your Wasp Spec.

Wasp generates the routes object and the types of Link's and NavLink's props from your app's routes, so linking to a route that doesn't exist, or passing the wrong params, is a type error.

Type Aliases​

LinkProps​

LinkProps = Omit<RouterLinkProps & RefAttributes<HTMLAnchorElement>, "to"> & RouteLinkProps

The props of the Link component.

Use this type to build your own component on top of Link while keeping its type safety.

Example​

import { Link, type LinkProps } from "wasp/client/router";

export function ButtonLink({ className, ...linkProps }: LinkProps) {
  return <Link {...linkProps} className={`button ${className ?? ""}`} />;
}

NavLinkProps = Omit<RouterNavLinkProps & RefAttributes<HTMLAnchorElement>, "to"> & RouteLinkProps

The props of the NavLink component.

Use this type to build your own component on top of NavLink while keeping its type safety.

Variables​

routes​

const routes: object

One RouteEntry for each route in your Wasp Spec, under the route's name.

Use it to build a route's URL from your own code, for example to navigate after a form submits.

For routes declared like this:

route("RootRoute", "/", page(MainPage)),
route("DetailRoute", "/task/:id/:userId?", page(DetailPage)),
route("OptionalRoute", "/task/:id/details?", page(TaskPage)),
route("CatchAllRoute", "/pages/*", page(CatchAllPage)),

Wasp generates routes with these build functions:

routes.RootRoute.build(options?: {
  search?: Search;
  hash?: string;
});

routes.DetailRoute.build(options: {
  params: { id: ParamValue; userId?: ParamValue };
  search?: Search;
  hash?: string;
});

routes.OptionalRoute.build(options: {
  path: "/task/:id/details" | "/task/:id";
  params: { id: ParamValue };
  search?: Search;
  hash?: string;
});

routes.CatchAllRoute.build(options: {
  params: { "*": ParamValue };
  search?: Search;
  hash?: string;
});

Index Signature​

[routeName: string]: RouteEntry

Example​

import { useNavigate } from "react-router";
import { routes } from "wasp/client/router";

export function NewPhotoForm() {
  const navigate = useNavigate();

  async function handleSubmit() {
    const photoId = await uploadPhoto(); // your upload logic
    navigate(routes.PhotoRoute.build({ params: { photoId } }));
  }

  // ...
}

See​

Navigating between pages

Components​

Link(props): Element

A link to one of your app's routes.

It behaves the same as React Router's Link and accepts all of its props, but to must be a route path from your Wasp Spec, and params must match the params in that path.

Parameters​

props​

LinkProps

Returns​

Element

Example​

import { Link } from "wasp/client/router";

export function PhotoCard({ photoId }: { photoId: string }) {
  return (
    <Link to="/photo/:photoId" params={{ photoId }} search={{ size: "large" }}>
      Photo {photoId}
    </Link>
  );
}

See​

Navigating between pages

NavLink(props): Element

A link to one of your app's routes that knows whether it's active or pending.

It behaves the same as React Router's NavLink and accepts all of its props, with the same to, params, search, and hash props as Link. Use it when the current page should be highlighted, or to show a spinner during a pending navigation.

The most useful React Router props are:

  • className, style, and children: besides regular values, these can be functions. NavLink calls them with an object describing the link's state and uses what they return. The object has these fields:
    • isActive: the link points to the current page.
    • isPending: the user clicked the link, and the page is still loading.
    • isTransitioning: a view transition to the page is in progress.
  • end: boolean: by default, a link is also active on nested paths. For example, a link to /tasks is active on /tasks/123. Set end to only make it active on its exact path.
  • caseSensitive: boolean: by default, the link ignores letter case when checking if it's active. Set caseSensitive to take case into account.

Parameters​

props​

NavLinkProps

Returns​

Element

Example​

import { NavLink } from "wasp/client/router";

export function Navigation() {
  return (
    <nav>
      <NavLink
        to="/tasks"
        className={({ isActive }) =>
          isActive ? "font-bold text-blue-600" : "text-gray-600"
        }
      >
        Tasks
      </NavLink>
    </nav>
  );
}

See​

Reacting to navigation state with NavLink

Referenced Types​

Params​

Params = object

Index Signature​

[name: string]: ParamValue

ParamValue​

ParamValue = string | number

RouteBuildOptions​

RouteBuildOptions = object

The options for building the URL of a route with RouteEntry.build.

Properties​

hash?​

optional hash?: string

The hash (fragment) of the URL.

params?​

optional params?: Params

The values for the params in the route's path, in the same form as RouteLinkProps.params. Required if the path contains params.

path?​

optional path?: string

Which variant of the path to build. Required (and only accepted) if the route's path has optional static segments. See RouteLinkProps.to for the values it takes.

optional search?: Search

The search params (query string), in the same shapes as RouteLinkProps.search.

RouteEntry​

RouteEntry = object

The entry that Wasp generates in routes for each route in your Wasp Spec.

Properties​

to​

readonly to: string

The route's path, as declared in your Wasp Spec, e.g. "/task/:id".

Methods​

build()​

build(options?): string

Builds the URL of the route, filling in its params, search params, and hash.

options is optional only if the route's path has no params and no optional static segments.

Parameters​
options?​

RouteBuildOptions

Returns​

string

The URL, e.g. "/task/42?tab=comments#notes".

RouteLinkProps​

RouteLinkProps = object

The props that pick which route a Link or NavLink points to, and how to fill in its URL.

Properties​

hash?​

optional hash?: string

The hash (fragment) of the URL, e.g. "comments" becomes #comments.

params?​

optional params?: Params

The values for the params in the path, e.g. { id: 1 } for /task/:id. Required if the path contains params. You can leave out optional params (:userId?).

For a splat path like /pages/*, pass the matched rest of the path as { "*": "some/path" }.

search?​

optional search?: Search

The search params (query string), in any shape the URLSearchParams constructor accepts. For example, { sortBy: "date" } becomes ?sortBy=date.

to​

to: string

The path of one of the routes in your Wasp Spec, exactly as you declared it, e.g. "/task/:id".

If the path has optional static segments, pass one of the paths that include or exclude them. For example, if the path is /task/:id/details?, pass either /task/:id/details or /task/:id.

Search​

Search = string[][] | Record<string, string> | string | URLSearchParams