handle7 methods, 4 fields

Router

In-app navigation for one region: a retained page stack with named routes and switchable roots (tabs). From panel:router(). Pages are kept (hidden) when backgrounded, so going back restores their scroll and state.

Obtained from: UiElement:router

The examples on this page start from:

lua

local router = datumhue.ui.root:router()

Fields 4

Field	Type	Access	Description
`depth`	integer	read-only	Number of pages on the active stack.
`active`	Route?	read-only	The active page's Route, or nil for an inline-pushed page.
`params`	table?	read-only	The active page's params (as passed to the navigator), or nil.
`can_go_back`	boolean	read-only	Whether the active stack has more than one page.

Methods 7

Router:route

method

Router:route(builder: function, options?: ui.RouteOptions) -> Route

Declare a route from a builder(page, params) that fills the given page element. Returns a Route handle to navigate to. Raises if the router was removed.

Example

local home = router:route(function(page, params)
    page:label({ text = "Home" })
end, {
    title = "Home",
    on_enter = function(page)
        print("entered")
    end,
})
router:show(home)

options ui.RouteOptions options 3 keys

Key	Type	Default	Description
title	string \| Message	the page announces no title and `route.title` reads nil	Accessible title (a plain string or a `datumhue.i18n.t(...)` message), announced to a screen reader on navigation and readable as `route.title`.
on_enter	function	no default	Called with the page element once it is built — start per-page work here.
on_leave	function	no default	Called when the page is about to be destroyed (pop/replace/to_root/go). Return `false` to veto and keep it (confirm-before-leave).

In the guide: Pages and tabs Handle Back

Router:show

methodsuspends

Router:show(route: Route, params?: table?)

Switch the active root to route (tabs); the previous root and its whole sub-stack are retained. Builds the route on first show. Raises if the router was removed.

Example

local inbox = router:route(function(page)
    page:label({ text = "Inbox" })
end)
local sent = router:route(function(page)
    page:label({ text = "Sent" })
end)
router:show(inbox)
router:show(sent)
print(router.active == sent) --> true

In the guide: Pages and tabs Handle Back

Router:push

methodsuspends

Router:push(target: Route | function, params?: table?)

Push a page onto the active stack (a Route or an inline builder(page, params)); the page below is hidden, retained. Raises if the router was removed.

Example

local item = router:route(function(page, params)
    page:label({ text = "Item " .. params.id })
end)
router:push(item, { id = 7 })

router:push(function(page)
    page:label({ text = "About" })
end)
print(router.depth, router.can_go_back) --> 2 true

In the guide: Pages and tabs Handle Back

Router:replace

methodsuspends

Router:replace(target: Route | function, params?: table?)

Replace the top page in place (no depth change). Runs the old page's on_leave (which may veto). Raises if the router was removed.

Example

local step = router:route(function(page, params)
    page:label({ text = "Step " .. params.n })
end)
router:push(step, { n = 1 })
router:replace(step, { n = 2 })
print(router.depth, router.params.n) --> 1 2

In the guide: Pages and tabs

Router:go

methodsuspends

Router:go(route: Route, params?: table?)

Navigate to route: if it is already on the active stack, pop back to it (retained); otherwise push it. Raises if the router was removed.

Example

local list = router:route(function(page)
    page:label({ text = "List" })
end)
local detail = router:route(function(page)
    page:label({ text = "Detail" })
end)
router:go(list)
router:go(detail)
router:go(list)
print(router.depth) --> 1

In the guide: Pages and tabs

Router:pop

methodsuspends

Router:pop()

Go back one page: discard the top and reveal the one below with its retained state. Runs the top's on_leave (may veto). No-op at the root; raises if the router was removed.

In the guide: Pages and tabs Handle Back

Router:to_root

methodsuspends

Router:to_root()

Pop every page above the active root and reveal the root with its retained state. Raises if the router was removed.

In the guide: Pages and tabs

`/` or `Ctrl` `K`	Search
`↑` `↓` `Enter`	Pick a result
`Tab`	Next result filter
`j` `k`	Next or previous entry
`[` `]`	Previous or next page
`y`	Copy a link to the current entry
`?`	These shortcuts
`Esc`	Close

Router

Fields 4

Methods 7

Router:route

Router:show

Router:push

Router:replace

Router:go

Router:pop

Router:to_root

Try

Recently viewed

Settings

Keyboard shortcuts

On this page