Interface: PlayRouteEvent

API / @xmachines/play-dom-router / PlayRouteEvent

Defined in: play-router/src/types.ts:237

The routing event, with its parameters and its query

This is the one routing event of the complete Play architecture. It supports a navigation that knows the parameters, for example /profile/:userId, for a dynamic route segment.

Architectural context: the event implements Passive Infrastructure (INV-04), because it holds the navigation intent of the user, and the Actor then evaluates that intent with its guards. The infrastructure makes a request with a play.route event, and the Actor decides with a transition of its state machine.

The flow of a browser navigation:

1. The browser fires popstate
2. The router adapter resolves the URL to a route target
3. The adapter sends a PlayRouteEvent to the Actor
4. The Actor checks the transition with the guards of its state machine

Param

type

The discriminator of the event. It is always “play.route”

Param

to

The target state ID, with a # prefix, for example ‘#home’ or ‘#profile’

Param

params

The route parameters of the path only, from the URL path, for example { userId: '123' } of /profile/123. The query field holds the query parameters separately.

Param

query

The query parameters only. They stay separate from the params of the path

Param

match

The complete match result of URLPattern, for the debug work and for the observability. It is optional

Examples

The base event and the routing event together

import type { PlayEvent } from "@xmachines/play";
import type { PlayRouteEvent } from "@xmachines/play-router";

type AppEvent = PlayEvent | PlayRouteEvent;

A basic navigation to a route

import type { PlayRouteEvent } from "@xmachines/play-router";

const event: PlayRouteEvent = {
  type: "play.route",
  to: "#home",
};
actor.send(event);

A navigation with route parameters

import type { PlayRouteEvent } from "@xmachines/play-router";

const event: PlayRouteEvent = {
  type: "play.route",
  to: "#profile",
  params: { userId: "123" },
};
actor.send(event);
// It resolves to the route /profile/123

A navigation with query parameters

import type { PlayRouteEvent } from "@xmachines/play-router";

const event: PlayRouteEvent = {
  type: "play.route",
  to: "#settings",
  params: { section: "profile" }, // a route parameter of the path only
  query: { tab: "security" }, // the query only
};
actor.send(event);
// It resolves to the route /settings/profile?tab=security

See

Play RFC

Remarks

Use play.route when you need a navigation that knows the parameters, with the route: {} config pattern on the nodes of your state machine. The match field gives you the complete URLPatternResult, for an advanced use such as a debug or an analysis of the pattern.

Indexable

[key: string]: unknown

Properties

Property	Modifier	Type	Defined in
match?	readonly	unknown	play-router/src/types.ts:242
params?	readonly	Record<string, string>	play-router/src/types.ts:240
query?	readonly	Record<string, string>	play-router/src/types.ts:241
to	readonly	string	play-router/src/types.ts:239
type	readonly	"play.route"	play-router/src/types.ts:238