API Reference

Functions

div()

Returns an ElementBuilder for a container element.

text(content: str)

Returns an ElementBuilder for text display.

button(label: str)

Returns an ElementBuilder for a button.

input()

Returns an ElementBuilder for a text input.

image(src: str)

Returns an ElementBuilder for an image.

checkbox(label: str = None)

Returns an ElementBuilder for a checkbox with optional label.

radio(label: str = None)

Returns an ElementBuilder for a radio button with optional label.

select()

Returns an ElementBuilder for a dropdown select.

UiWindow

class UiWindow(title=None, width=None, height=None, background_color=None)
Parameters:

  • title – Window title. Default: "Python App"

  • width – Width in pixels. Default: 800

  • height – Height in pixels. Default: 600

  • background_color – Hex color. Default: "#1a1a1a"

set_root(element: Element)

Set the root element and render it.

set_title(title: str)

Change the window title.

update_element(element_id: str, element: Element)

Update a single element by ID. More efficient than set_root() when only a small part of the UI changes. The element must have an ID set via the id() builder method.

run()

Start the event loop. Blocks until the window closes.

close()

Close the window and exit the event loop.

is_running() → bool

Returns True if the event loop is running.

AppBase

class AppBase

Base class intended for application code. Subclass this in Python to encapsulate application state and rendering logic. Typical usage is to implement render() and call set_window() to attach a UiWindow.

set_window(window: UiWindow)

Attach a UiWindow instance to the app. The app can use window.set_root(...) to update the UI.

render()

Build and set the root element for the window. Subclasses MUST implement this method and call self.window.set_root(...) with the constructed Element.

run()

Convenience: render once and start the window event loop. Raises RuntimeError if no window has been attached.

set_root(element: Element)

Convenience wrapper to call window.set_root(element). Raises RuntimeError if no window is attached.

on_start()

Optional lifecycle hook invoked before run() begins.

on_close()

Optional lifecycle hook invoked after the window closes.

Element

class Element(element_type=None)

Immutable element. Created by calling .build() on an ElementBuilder.

to_json() → str

Serialize to JSON.

ElementBuilder

AssetCatalog

class AssetCatalog

Register binary assets (images, fonts) from Python so the renderer can embed them as data URIs and avoid file:// permission issues in the webview.

add(name: str, data: bytes)

Add raw bytes under name to the global asset catalog.

get_data_uri(name: str) → str | None

Return a data: URI for the registered asset, or None if not present.

All methods return self for chaining unless noted.

Factory Methods

classmethod ElementBuilder.div()
classmethod ElementBuilder.text(content: str)
classmethod ElementBuilder.button(label: str)
classmethod ElementBuilder.image(src: str)
classmethod ElementBuilder.input()
classmethod ElementBuilder.checkbox(label: str = None)
classmethod ElementBuilder.radio(label: str = None)
classmethod ElementBuilder.select()

Size

width(w: float)
height(h: float)
size(w: float, h: float)
size_full()

Sets width and height to 100%.

full_width()

Sets width to 100%.

full_height()

Sets height to 100%.

min_width(w: float)

Minimum width in pixels.

max_width(w: float)

Maximum width in pixels.

min_height(h: float)

Minimum height in pixels.

max_height(h: float)

Maximum height in pixels.

Layout

v_flex()

Vertical flex layout (column).

h_flex()

Horizontal flex layout (row).

items_center()

Center items on the cross axis.

justify_center()

Center items on the main axis.

justify_between()

Space between items.

gap(g: float)

Gap between children in pixels.

flex_wrap()

Allow flex items to wrap to multiple lines.

flex_nowrap()

Prevent flex items from wrapping.

flex_grow(value: float)

Set flex grow factor.

flex_shrink(value: float)

Set flex shrink factor.

flex_basis(value: str)

Set flex basis (initial size).

flex_1()

Shorthand for flex-grow: 1; flex-shrink: 1; flex-basis: 0%.

align_self(value: str)

Align this item differently from siblings.

Grid

grid()

Enable CSS grid layout on this element.

grid_cols(value: str)

Set grid template columns (e.g., "1fr 1fr 1fr" or "repeat(3, 1fr)").

grid_rows(value: str)

Set grid template rows (e.g., "auto 1fr auto").

col(value: str)

Set which column(s) this item spans (e.g., "1 / 3" or "span 2").

row(value: str)

Set which row(s) this item spans (e.g., "1 / 3" or "span 2").

place_items(value: str)

Set alignment for grid items (e.g., "center").

place_center()

Center grid items both horizontally and vertically.

Padding

padding(y: float, x: float = None)

One arg: all sides. Two args: vertical, horizontal.

p(y: float, x: float = None)

Alias for padding().

pt(p: float)
pr(p: float)
pb(p: float)
pl(p: float)
px(p: float)

Left and right.

py(p: float)

Top and bottom.

margin(m: float)
m(m: float)

Alias for margin().

mt(m: float)

Set top margin (pixels).

mr(m: float)

Set right margin (pixels).

mb(m: float)

Set bottom margin (pixels).

ml(m: float)

Set left margin (pixels).

mx(m: float)

Set horizontal margins (left and right) (pixels).

my(m: float)

Set vertical margins (top and bottom) (pixels).

Styling

bg(color: str)

Background color (hex or CSS). For checkboxes/radios, sets the accent color.

text_color(color: str)
rounded(radius: float)

Border radius in pixels.

rounded_tl(radius: float)

Set top-left corner radius (pixels).

rounded_tr(radius: float)

Set top-right corner radius (pixels).

rounded_br(radius: float)

Set bottom-right corner radius (pixels).

rounded_bl(radius: float)

Set bottom-left corner radius (pixels).

border(width: float, color: str)
border_top(width: float, color: str)

Set border on the top side (width in pixels and color).

border_right(width: float, color: str)

Set border on the right side (width in pixels and color).

border_bottom(width: float, color: str)

Set border on the bottom side (width in pixels and color).

border_left(width: float, color: str)

Set border on the left side (width in pixels and color).

b(color: str)

1px solid border.

overflow_hidden()
overflow(value: str)

Text

text_size(size: float)

Font size in pixels.

text_weight(weight: str)

"normal", "bold", or "100"-"900".

text_align(align: str)
text_center()
word_wrap(value: str)

Transitions

transition_all(seconds: float)

Transition all properties with the given duration.

transition_colors(seconds: float)

Transition background, text, and border colors.

transition_transform(seconds: float)

Transition transform (scale, etc.).

transition(value: str)

Raw CSS transition value for advanced use.

Effects

opacity(value: float)

Set opacity (0.0 to 1.0).

cursor(value: str)

Set cursor style ("pointer", "grab", "not-allowed").

style(css: str)

Apply raw CSS styles directly. Multiple calls append to existing styles.

div().style("box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1)")

Hover Styles

hover_bg(color: str)
hover_text_color(color: str)
hover_border_color(color: str)
hover_opacity(value: float)
hover_scale(value: float)

Scale on hover (e.g., 1.05 for 5% larger).

Focus Styles

focus_bg(color: str)
focus_text_color(color: str)
focus_border_color(color: str)

Position

position(value: str)

"static", "relative", "absolute", "fixed".

absolute()
relative()
top(value: float)
bottom(value: float)
left(value: float)

Children

child(child: Element)

Add an Element as a child.

child_builder(child: ElementBuilder)

Add an ElementBuilder as a child. Calls .build() internally.

child_text(text: str)

Add text as a child.

Events

on_click(callback: Callable[[], None])

Register a click handler.

on_input(callback: Callable[[str], None])

Register an input handler. Receives the current value.

on_change(callback: Callable[[str], None])

Register a change handler for checkbox, radio, or select. Receives the new value.

on_mouse_enter(callback: Callable[[], None])

Register a handler for mouse enter.

on_mouse_leave(callback: Callable[[], None])

Register a handler for mouse leave.

on_mouse_down(callback: Callable[[], None])

Register a handler for mouse button press.

on_mouse_up(callback: Callable[[], None])

Register a handler for mouse button release.

Image

alt(text: str)

Set alt text for accessibility.

object_fit(value: str)

Set object-fit ("cover", "contain", "fill").

Input

value(val: str)

Set the input value.

placeholder(text: str)

Set placeholder text.

Checkbox / Radio

checked(checked: bool)

Set checked state.

group(name: str)

Set radio button group name. Radio buttons with the same group are mutually exclusive.

Select

option(value: str, label: str)

Add an option to a select dropdown.

selected(value: str)

Set the selected option value.

Identification

id(id: str)

Set an ID for targeting with update_element().

class_name(name: str)

Add a CSS class name.

classes(names: list[str])

Add multiple CSS class names.

Build

build() → Element

Finalize and return the Element.