Duolith docs

0041. canGoBack() and backTitle() say whether a screen was pushed, and from what

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: integrator (internal only), pending Mik's approval
  • Planning item: WP7 (kit)

Context

The kit's NavHeader shows a back button "when there is a screen to go back to", named "Back" or "Back to <previous title>". Nothing in the router said so: back() always does something (it goes one level up the path when the app was opened at this screen, decision 0031), and history length counts other sites and tabs. On iOS and Android the rule is simple: a screen pushed onto a navigation stack has a back button; the first screen of a stack, and a tab's root, do not.

Decision

  • Each history entry records the screen it was pushed from, with the title that screen showed. The router keeps the title of each entry once its screen has been shown; a push made while the previous navigation is still loading records no title (the button says "Back"), never the title of the screen before that. An entry written before entries recorded this (by an older version of the router) counts as pushed when its number is above 0, with no title. It is kept as { previous: { title } }, or previous: null for none, beside the entry number in the History API state. A push (a link inside a screen, navigate()) records it. A switch (a link in a layout's own markup, such as a tab), the first screen of a visit and going up a level when nothing is behind record none. A replace (navigate(..., { replace: true }), a guard's redirect) keeps what the replaced entry had, so a sign-in screen that replaced a guarded one still goes back where the user came from. Reload keeps it, because it lives in the entry's state.
  • **canGoBack() is true when the screen in front has a previous screen; backTitle()** is that screen's title, if it had one. Like route(), a page's screen knows this from when it was made (its scope carries it), and a layout follows the screen in front, so a header in a layout updates as screens are pushed.
  • Back passes over #fragment entries. Moving to #section of a screen adds history entries for the same screen; back() (and a link back to an earlier screen) goes on past them to the screen before, rather than leaving the user on the same screen.
  • Up, for a screen with nothing to go back to. Decision 0031's back() still goes one level up the path when the app was opened at the screen, but a back button that does that would also appear on every tab's first screen. So the header asks instead: <NavHeader up="/profile" upTitle="Profile"> shows an up button, named "Up to Profile", only when canGoBack() is false, and it replaces the screen with that route. The route is the page's to name, because the path's parent is often not a screen (/post for /post/7).
  • NavHeader uses them: <show when={showBack && canGoBack()}> a button named Back to <title> (or Back) showing the title, which calls back() or the onBack prop.

Alternatives considered

OptionWhy not
A field on route()route() gives the route's parameters by name; another reserved name would take a parameter name away
history.length > 1Counts other sites and entries before the app, and cannot tell a tab from a push
entry > 0A tab's root would show a back button that goes to another tab
Show back whenever back() would do somethingEvery screen opened from a shared link would have one that leaves for a page the user never saw

Consequences

  • Native targets know the same thing from their navigation stacks; the Navigator contract does not change.
  • A screen opened straight from its address has no back button; it has an up button when its header names up.