NavigationStack & NavigationLink¶
NavigationStack and NavigationLink work together to create hierarchical drill-down navigation interfaces. NavigationStack manages a stack of views, and NavigationLink creates tappable elements that push destination views onto the stack.
The stack maintains navigation history, allowing users to return to previous views. The root content is always at the bottom of the stack, with destination views pushed on top as the user navigates.
Constructor¶
nib.NavigationStack(
controls=None,
routes=None,
initial=None,
show_back_button=True,
on_navigate=None,
**modifiers,
)
nib.NavigationLink(
label=None,
destination=None,
**modifiers,
)
Parameters¶
NavigationStack¶
| Parameter | Type | Default | Description |
|---|---|---|---|
controls |
list[View] |
None |
Root views. Navigate with NavigationLink. Ignored when routes is set. |
routes |
dict[str, Callable[[], View]] |
None |
Route mode. Maps route names to functions that build the page. A page is built on each push(). |
initial |
str |
None |
Route shown first. Must be a key of routes. |
show_back_button |
bool |
True |
Show the back button on pushed routes. |
on_navigate |
Callable[[str], None] |
None |
Called with the route name whenever the visible route changes, including the back button and swipe back. |
**modifiers |
Common view modifiers: padding, background, foreground_color, opacity, width, height, etc. |
NavigationLink¶
| Parameter | Type | Default | Description |
|---|---|---|---|
label |
str |
required | The text label displayed for the navigation link. This text is shown as the tappable element. |
destination |
list[View] |
None |
Views to display when the link is tapped. These views are pushed onto the NavigationStack. |
**modifiers |
Common view modifiers: padding, background, foreground_color, opacity, etc. |
Methods¶
Route mode only.
| Method | Description |
|---|---|
push(route) |
Build the route's page and push it. Unknown names are ignored. |
pop() |
Pop the top route. Applied after the next render. |
pop_to_root() |
Pop every pushed route, back to initial. |
nav = nib.NavigationStack(
routes={"home": home_page, "about": about_page},
initial="home",
)
nib.Button("About", action=lambda: nav.push("about"))
Examples¶
Basic navigation¶
import nib
def main(app: nib.App):
app.title = "Recipes"
app.icon = nib.SFSymbol("book")
app.width = 280
app.height = 240
def recipe(name, minutes, steps):
return nib.NavigationLink(
name,
destination=[
nib.VStack(
controls=[
nib.Text(name, font=nib.Font.TITLE2),
nib.Text(
f"{minutes} minutes", foreground_color=nib.Color.SECONDARY
),
*[nib.Text(f"{i}. {step}") for i, step in enumerate(steps, 1)],
],
spacing=8,
padding=16,
alignment=nib.Alignment.LEADING,
)
],
)
app.build(
nib.NavigationStack(
controls=[
nib.List(
controls=[
recipe(
"Carbonara",
20,
[
"Boil the pasta",
"Fry the guanciale",
"Mix eggs and pecorino",
"Toss off the heat",
],
),
recipe(
"Pesto",
10,
[
"Blend basil, pine nuts and garlic",
"Add oil and parmesan",
],
),
recipe(
"Risotto",
35,
[
"Toast the rice",
"Add stock a ladle at a time",
"Mantecare with butter",
],
),
]
)
],
width=280,
height=220,
)
)
nib.run(main)
Settings navigation with sections¶
import nib
def main(app: nib.App):
app.title = "Settings"
app.icon = nib.SFSymbol("gearshape")
app.width = 280
app.height = 280
def page(title, *controls):
return [
nib.VStack(
controls=[nib.Text(title, font=nib.Font.TITLE2), *controls],
spacing=12,
padding=16,
alignment=nib.Alignment.LEADING,
)
]
app.build(
nib.NavigationStack(
controls=[
nib.List(
controls=[
nib.Section(
controls=[
nib.NavigationLink(
"Profile",
destination=page(
"Profile",
nib.TextField("Display name", value="Jane"),
),
),
nib.NavigationLink(
"Notifications",
destination=page(
"Notifications",
nib.Toggle("Push", is_on=True),
nib.Toggle("Email", is_on=False),
),
),
],
header="Account",
),
nib.Section(
controls=[
nib.NavigationLink(
"Privacy",
destination=page(
"Privacy",
nib.Toggle("Share analytics", is_on=False),
),
),
nib.NavigationLink(
"About",
destination=page("About", nib.Text("nib 1.2.0")),
),
],
header="General",
),
]
)
],
width=280,
height=260,
)
)
nib.run(main)