D Donkeh docs
GitHub

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.

RouteMatches
/Only the root path.
/settingsExactly /settings.
/docs/*/docs and every descendant such as /docs/intro.
*Every path. Put it last if you use it as a catch-all.
aboutNormalised 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:

ContextValue
Router.PathThe current normalised path as a string.
Router.SetPageAn 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)));
}
setPage is not browser navigation The router stores a string. It does not update the URL, push history or intercept the back and forward buttons. A host can persist the current path or feed it into AppRouter through InitialPath. Calling UseContext(Router.SetPage) outside an AppRouter gets the default no-op action.

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

PatternApproach
Lazy pagesUse the Route(path, Func<Node?>) overload so page trees are built only when matched.
Section layoutReturn a layout component from a wildcard route, then render AppRoutes again inside it for child pages.
Current page in a headerRead Router.Path in any component under AppRouter.
Programmatic navigationRead Router.SetPage in an event handler or effect; do not call setters during render.
Not foundSet AppRoutesProps.Fallback, or add a final Route("*", ...).