Routing and setPage
The router is a small, host-agnostic path store. It decides which route
content is rendered and exposes the current path plus a
setPage action through context. It does not touch a URL bar,
browser history or the network.
A route table
Import Donkeh.UILab.Routing for the factories and wrap the app
in AppRouter. AppRoutes renders the first
matching Route.
using Donkeh.Hosting;
using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;
using static Donkeh.UILab.Routing;
[AppRoot(Width = 1000, Height = 700, Title = "My app")]
public sealed class App : Component
{
public override Node Render() =>
AppRouter("/",
AppRoutes(
Route("/", () => Home()),
Route("/settings", () => Settings()),
Route("/docs/*", () => Docs())));
}
private static Node Home() =>
Div(new() { ClassName = "page" },
H1(new(), Text("Home")),
Link("/settings", Text("Open settings")));
private static Node Settings() =>
Div(new() { ClassName = "page" }, H1(new(), Text("Settings")));
private static Node Docs() =>
Div(new() { ClassName = "page" }, H1(new(), Text("Docs")));
A factory overload such as Route("/settings", () => Settings())
builds the page only when it matches. The children overload is fine for
cheap pages:
AppRoutes(
Route("/", Text("Home")),
Route("/about", Text("About")));
Paths and matching
Routes and pages are compared after normalisation: the path gets a leading slash, duplicate slashes collapse, a trailing slash is removed, and a query string or fragment is dropped. Paths are case-sensitive.
| Route | Matches |
|---|---|
/ | Only the root path. |
/settings | Exactly /settings. |
/docs/* | /docs and every descendant such as /docs/intro. |
* | Every path. Put it last if you use it as a catch-all. |
about | Normalised to /about. |
AppRoutes takes the first match in declaration order. For a
not-found page, construct the props directly so the fallback is available:
using static Donkeh.UILab._;
C<AppRoutes, AppRoutesProps>(new AppRoutesProps
{
Children =
[
Route("/", Text("Home")),
Route("/settings", Text("Settings"))
],
Fallback = Text("Not found")
});
Reading the path and calling setPage
AppRouter publishes two context values:
| Context | Value |
|---|---|
Router.Path | The current normalised path as a string. |
Router.SetPage | An Action<string> that navigates to a new path. |
using Donkeh.UILab;
using static Donkeh.UILab.HtmlHelper;
using static Donkeh.UILab._;
public sealed class SaveButton : Component
{
public override Node Render()
{
var setPage = UseContext(Router.SetPage);
return Button(new()
{
ClassName = "primary",
OnClick = () => setPage("/done")
}, Text("Finish"));
}
}
A component can also read the current path. It re-renders when the router publishes a new value, because the component sits under the provider:
public sealed class PathLabel : Component
{
public override Node Render() =>
Span(new() { ClassName = "path" },
Text(UseContext(Router.Path)));
}
AppRouter through InitialPath.
Calling UseContext(Router.SetPage) outside an
AppRouter gets the default no-op action.
Links and active state
Link renders an anchor and calls setPage on click
instead of relying on browser navigation. It adds the active
class while the target is the current path or an ancestor of it:
Nav(new() { ClassName = "nav" },
Link("/", Text("Home")),
Link("/settings", Text("Settings")),
Link("/docs", Text("Docs")));
// A link is active on /docs and /docs/intro,
// but the root link is only active on /.
Pass ActiveClassName to change the class, or an empty string to
disable it:
C<Link, LinkProps>(new LinkProps
{
To = "/settings",
ActiveClassName = "is-current",
Children = [Text("Settings")]
});
Useful patterns
| Pattern | Approach |
|---|---|
| Lazy pages | Use the Route(path, Func<Node?>) overload so page trees are built only when matched. |
| Section layout | Return a layout component from a wildcard route, then render AppRoutes again inside it for child pages. |
| Current page in a header | Read Router.Path in any component under AppRouter. |
| Programmatic navigation | Read Router.SetPage in an event handler or effect; do not call setters during render. |
| Not found | Set AppRoutesProps.Fallback, or add a final Route("*", ...). |