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 } }, orprevious: nullfor none, beside the entry number in the History API state. A push (a link inside a screen,navigate()) records it. Aswitch(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. Likeroute(), 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
#sectionof 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 whencanGoBack()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 (/postfor/post/7). - NavHeader uses them:
<show when={showBack && canGoBack()}>a button namedBack to <title>(orBack) showing the title, which callsback()or theonBackprop.
Alternatives considered
| Option | Why not |
|---|---|
A field on route() | route() gives the route's parameters by name; another reserved name would take a parameter name away |
history.length > 1 | Counts other sites and entries before the app, and cannot tell a tab from a push |
entry > 0 | A tab's root would show a back button that goes to another tab |
Show back whenever back() would do something | Every 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
Navigatorcontract does not change. - A screen opened straight from its address has no back button; it has an up button when its header names
up.