Routing

For applications that require multiple screens or scenes, Vulpis provides a lightweight, Single Page Application (SPA) style router in the utils/core/router.lua module.

The router uses the engine's built-in state management to dynamically swap out UI components based on the current path, allowing for seamless scene navigation without reloading the application.

API Reference

router.define(routeTable)

Registers the available routes in your application.

• routeTable: A table where keys are string paths (e.g., "/", "/settings") and values are functions that return a Vulpis node (your screen components).

router.push(path)

Navigates the application to a new route. This updates the internal state (__router_current_path) and automatically triggers a UI re-render.

• path: A string representing the path to navigate to. This must match a key you provided in your routeTable.

router.render()

Returns the UI component for the currently active route. If the current path does not exist in the routeTable, it automatically returns a built-in 404 fallback screen.

Example Usage

Here is a complete example showing how to define routes, navigate between them, and render the router in your main application entry point.

local el = require("utils.core.elements")
local router = require("utils.core.router")

function HomePage()
	return el.VBox({
		style = {
			justifyContent = "center",
			alignItems = "center",
			padding = 10,
			BGColor = "#181a21",
			w = "100%",
			h = "100%",
		},
		children = {
			el.Text("Home Page", { fontSize = 40, color = "#ecf542" }),
		},

		onClick = function()
			router.push("/settings")
		end,
	})
end

function Settings()
	return el.VBox({
		style = {
			justifyContent = "center",
			alignItems = "center",
			padding = 10,
			BGColor = "#181a21",
			w = "100%",
			h = "100%",
		},
		children = {
			el.Text("Settings Page", { fontSize = 40, color = "#5af542" }),
		},

		onClick = function()
			router.push("/")
		end,
	})
end

router.define({
	["/"] = HomePage,
	["/settings"] = Settings,
})

function App()
	return el.VBox({
		children = {
			el.HBox({
				style = {
					w = "100%",
					justifyContent = "space-between",
					alignItems = "center",
					px = 10,
					py = 10,
					BGColor = "#070708",
				},
				children = {
					el.Text("APP", { color = "#ff758f", fontSize = 20 }),
					el.HBox({
						style = {
							alignItems = "center",
							justifyContent = "center",
							spacing = 15,
						},

						children = {
							el.Button({
								text = "Settings",
								style = {
									BGColor = { 0, 0, 0, 0 },
									color = "#FFFFFF",
									px = 0,
									py = 0,
								},
								onClick = function()
									router.push("/settings")
								end,
							}),

							el.Button({
								text = "Home",
								style = {
									BGColor = { 0, 0, 0, 0 },
									color = "#FFFFFF",
									px = 0,
									py = 0,
								},
								onClick = function()
									router.push("/")
								end,
							}),
						},
					}),
				},
			}),
			router.render(),
		},
	})
end