ui-elements

talon-ui-elements

Python canvas UI library for Talon voice control runtime.

• NOT web/browser - renders on a Skia canvas. No HTML, CSS, DOM, or browser APIs.
• Everything is flexbox. No display: block/inline/grid. Every container is a flex container.
• flex_direction defaults to "column" - children stack vertically. Use flex_direction="row" for horizontal.
• align_items defaults to "stretch" on containers (divs), "flex_start" on screen.
• Runs inside Talon's Python runtime (no pip, no virtualenv, no build step). Talon hot-reloads .py files on save.
• React-inspired declarative API with CSS-like properties (flexbox layout, styling kwargs).
• Import: from talon import actions → call actions.user.ui_elements(["div", "text", "screen", ...]) to get element constructors.
• All UI code lives in plain .py files inside the Talon user directory.

---

Minimal Example

from talon import actions

def hello_world_ui():
    div, text, screen = actions.user.ui_elements(["div", "text", "screen"])

    return screen(justify_content="center", align_items="center")[
        div(background_color="#333333", padding=16, border_radius=8, border_width=1)[
            text("Hello world", color="#FFFFFF", font_size=24)
        ]
    ]

def show_hello_world():
    actions.user.ui_elements_show(hello_world_ui)

def hide_hello_world():
    actions.user.ui_elements_hide(hello_world_ui)

def toggle_hello_world():
    actions.user.ui_elements_toggle(hello_world_ui)

---

Getting Elements

Destructure element constructors from actions.user.ui_elements(...):

div, text, screen = actions.user.ui_elements(["div", "text", "screen"])
button, input_text, state = actions.user.ui_elements(["button", "input_text", "state"])
ref, effect, icon = actions.user.ui_elements(["ref", "effect", "icon"])
style, component = actions.user.ui_elements(["style", "component"])
window = actions.user.ui_elements("window")  # single element returns directly

All elements: div, text, code, screen, button, input_text, textarea, select, data_table, form, state, ref, effect, icon, style, component, link, checkbox, switch, table, tr, td, th, window, active_window

SVG elements (must be used inside svg()): svg, path, rect, circle, line, polyline, polygon

---

Element Hierarchy

• Root must be screen() or active_window()
• Children via bracket syntax: parent()[child1, child2]
• Containers (can have children): div, form, window, table, tr, td, th, screen, active_window, svg
• Leaves (no children): text, code, icon, checkbox, switch, input_text, textarea, select, data_table, link
• button: leaf with label button("Click"), container without: button(on_click=fn)[icon("check")]
• Dynamic lists: div()[*[text(item) for item in items]]

See patterns.md for common layout patterns, tab navigation, and complete examples.

---

Properties Quick Reference

All properties are kwargs: div(background_color="333333", padding=16).

• Layout: flex_direction ("column"/"row"), justify_content, align_items, align_self, flex, gap, flex_wrap
• Sizing: width, height, min_width, max_width, min_height, max_height - pixels or "100%"
• Spacing: padding, margin - plus _top, _right, _bottom, _left variants
• Position: position ("static"/"relative"/"absolute"/"fixed"), top, left, right, bottom
• Colors: background_color, color, border_color - hex strings ("FF0000", "#FF0000", "FF000080") or named colors
• Gradients: background="linear_gradient(to_right, FF0000, 0000FF)" - directions: to_right, to_left, to_bottom, to_top, or angle like 45deg
• Font: font_size (default 16), font_weight ("normal"/"bold"), font_family, text_align ("left"/"center"/"right"), white_space ("normal"/"nowrap")
• Border: border_width, border_radius, border_color - plus individual sides (border_top, etc.)
• Interactivity: on_click, on_change, highlight_style, disabled, draggable, drag_handle, autofocus
• Animation: transition, mount_style, unmount_style
• Identity: id, key, class_name, z_index
• Scrolling: overflow / overflow_y / overflow_x = "scroll" | "hidden"
• Other: opacity (0.0-1.0, cascades), drop_shadow

See properties.md for full tables with types and defaults.

---

State Management

All state is global - any UI or voice command can read/write any key. State is shared across UIs, so one UI can react to state set by another UI or by a voice command.

state = actions.user.ui_elements("state")

value = state.get("key", default)                    # Read-only snapshot
value, set_value = state.use("key", default)         # Reactive (triggers re-render)
state.set("key", new_value)                          # Set directly

set_value(lambda prev: prev + 1)                     # Lambda setter
set_items(lambda prev: prev + [new_item])            # Append to list

External access (from voice commands / outside UI):

actions.user.ui_elements_set_state("key", value)
actions.user.ui_elements_set_state("count", lambda prev: prev + 1)
actions.user.ui_elements_set_state({"key1": "val1", "key2": "val2"})  # batch
actions.user.ui_elements_get_state("key")
actions.user.ui_elements_get_state("key", "default_value")

Initial state (pre-set before first render):

actions.user.ui_elements_show(my_ui, initial_state={"tab": "home", "items": []})

See: docs/concepts/state.md

---

Refs

Direct element access for input fields. Requires matching id prop. Only use in callbacks or effects, not during initial render.

ref = actions.user.ui_elements("ref")
input_ref = ref("my_input")

input_ref.value       # Read current value
input_ref.clear()     # Clear the input
input_ref.focus()     # Focus the input

See: docs/concepts/ref.md

---

Effects (Lifecycle)

effect = actions.user.ui_elements("effect")

# Mount only:
effect(on_mount, [])

# Mount + unmount:
effect(on_mount, on_unmount, [])

# State change:
effect(on_tab_change, ["active_tab"])  # deps are string state key names

# Mount with cleanup:
def on_mount():
    return lambda: print("Cleanup!")
effect(on_mount, [])

See: docs/concepts/effect.md

---

Style Blocks

CSS-like selectors for shared styles:

style = actions.user.ui_elements("style")

style({
    "*": {"color": "CCCCCC"},                        # Universal
    "text": {"font_size": 14},                       # Tag selector
    "#my_id": {"background_color": "333333"},        # ID selector
    ".my_class": {"padding": 12, "border_radius": 6},  # Class selector
})

button("Click", class_name="my_class")

See: docs/concepts/style.md

---

Elements Quick Reference

• screen() / active_window() - Root containers. screen(1) for second monitor. active_window() follows focused OS window.
• div() - Generic container.
• text("content") - Display text.
• code("def hello():") - Syntax-highlighted code. Props: language ("python"/"talon"), theme, diff=True, copyable=True. Monospace font by default.
• form(on_submit=fn) - Form container. Enter in child input_text or clicking a child button(type="submit") triggers on_submit. Callback receives SubmitEvent(data={"input_id": "value", ...}) with all child input values. Ctrl+Enter submits from textarea.
• button("label", on_click=fn) - Interactive button. Container when no label: button(on_click=fn)[icon("check")]. Use type="submit" inside a form to trigger the form's on_submit.
• input_text(id="x") - Text input. Requires id. Supports placeholder, autofocus, on_change.
• textarea(id="x", rows=5) - Multi-line input. Requires id.
• select(id="x", options=[...]) - Dropdown. Requires id. Options: strings or {"label": "...", "value": "..."} dicts.
• checkbox(checked=True, on_change=fn) - Toggle. Uses on_change not on_click.
• switch(checked=True, on_change=fn, animated=True) - Toggle switch. Uses on_change not on_click. animated enables smooth transitions. size scales dimensions (default 14).
• link("text", url="...") - Clickable URL. close_on_click=True to hide UI after click.
• icon("name", size=24) - Built-in SVG icon (Lucide-style, 24x24 viewbox). ~48 available names: arrow_down, arrow_left, arrow_right, arrow_up, check, chevron_down, chevron_left, chevron_right, chevron_up, close, clock, copy, delta, diamond, download, edit, external_link, file, file_text, folder, home, maximize, menu, mic, minimize, minus, more_horizontal, more_vertical, multiply, pause, play, plus, rotate_left, settings, shrink, star, stop, trash, upload.
• window(title="...") - Draggable panel with title bar, minimize, close buttons.
• table() / tr() / th() / td() - Table structure.
• component(fn, props) - Reusable UI with local state (state.use_local). Only needed for local state or scoped styles.
• svg() / path() / rect() / circle() / line() - Custom SVG. Use size and view_box, not width/height/viewBox. Icons use a 24x24 viewbox. To create a custom icon:

svg, path, circle = actions.user.ui_elements(["svg", "path", "circle"])
# defaults: size=24, view_box="0 0 24 24", stroke_width=2, stroke_linecap/linejoin="round"
svg()[
    circle(cx=12, cy=12, r=10),
    path(d="M12 6v6l4 2"),
]

See: docs/elements.md

---

Show / Hide API

actions.user.ui_elements_show(my_ui)                                    # Show
actions.user.ui_elements_show(my_ui, initial_state={...})               # With initial state
actions.user.ui_elements_show(my_ui, duration="2s")                     # Auto-hide
actions.user.ui_elements_show(my_ui, on_mount=fn, on_unmount=fn) 

---

*Content truncated.*