Built-in Widgets

All built-in widgets are available via import Plushie.UI. Each widget has a corresponding typed builder module under Plushie.Widget.* for programmatic use.

Widget catalog

Layout

Full prop tables for all layout containers are in the Layout reference.

Input

button is the simplest interactive widget. The label is the second positional argument. Emits :click on press.

text_input is a single-line editable field. Emits :input on every keystroke with the full text as value. Emits :submit on Enter when on_submit: true is set. Emits :paste when on_paste: true is set.

text_editor is a multi-line editable area with syntax highlighting support (highlight_syntax: "ex"). The content argument seeds the initial text. Holds renderer-side state (cursor, selection, scroll).

checkbox / toggler are boolean toggles. Both emit :toggle with the new boolean value. checkbox shows a box; toggler shows a switch. Add label: for accessible text.

slider / vertical_slider are range inputs. range is a {min, max} tuple. Emits :slide continuously while dragging and :slide_release when the drag ends with the final value.

pick_list is a dropdown selection. options is a list of strings. selected is the currently selected value (or nil). Emits :select when an option is chosen.

combo_box is a searchable dropdown. Combines a text input with a filtered option list. Holds renderer-side state (search text, open state). Emits :input on typing and :select on option selection.

radio is a one-of-many selection. value is the option this radio represents; selected is the currently selected value from the model. The radio is checked when value == selected. Emits :select with the radio's value.

Display

text supports auto-ID (text("Hello")) and explicit-ID (text("greeting", "Hello")). Key props: size, color, font, wrapping, shaping, align_x, align_y.

rich_text displays styled text with individually formatted spans. Each span is a map with optional keys: text (content), size, color, font, link (clickable URL), underline, strikethrough, line_height, padding, and highlight (background with optional border). Example:

rich_text("greeting", [
  %{text: "Hello, ", size: 16},
  %{text: "world", size: 16, color: "#3b82f6", underline: true},
  %{text: "!", size: 16}
])

tooltip wraps a child widget. The child is the anchor; tip is the tooltip text. Props: position (:top, :bottom, :left, :right, :follow_cursor), gap.

image renders a raster image. Two source modes:

• Path-based (preferred): image("photo", "path/to/file.png"). The renderer loads the file directly. No wire transfer.
• Handle-based: image("photo", handle: "avatar"). References an in-memory image created via Command.create_image/2.

Key props: content_fit, filter_method, width, height, opacity, rotation (degrees), border_radius, scale, crop (%{x, y, width, height}), alt (accessible label).

In-memory image handles:

# Create from encoded PNG/JPEG bytes:
{model, Command.create_image("avatar", png_bytes)}

# Create from raw RGBA pixels:
{model, Command.create_image("avatar", 512, 512, rgba_pixels)}

# Reference in view:
image("display", handle: "avatar")

# Update pixels:
{model, Command.update_image("avatar", new_pixels)}

# Delete:
{model, Command.delete_image("avatar")}

Handle-based images send the entire payload over the wire in a single message, which blocks all other protocol traffic for large images. Prefer path-based loading when the file exists on disk. A chunked streaming alternative for large dynamic images is planned.

canvas contains named layers of shapes. See the Canvas reference.

Table

Plushie.Widget.Table

Data table with typed columns, rows, sorting, and scrolling.

table "users",
  columns: [
    %{key: "name", label: "Name", sortable: true},
    %{key: "email", label: "Email", width: {:fill_portion, 2}},
    %{key: "role", label: "Role", align: "center", sortable: true}
  ],
  rows: [
    %{"name" => "Alice", "email" => "alice@example.com", "role" => "Admin"},
    %{"name" => "Bob", "email" => "bob@example.com", "role" => "User"}
  ],
  sort_by: model.sort_by,
  sort_order: model.sort_order

Column format

Maps with these keys:

Row format

Rows are string-keyed maps where keys match column key values. String keys are required to avoid dynamic atom creation from external data (databases, JSON APIs). Values are rendered as text via to_string/1.

Table props

Sorting

Set sortable: true on columns that support sorting. The table emits :sort events when a sortable header is clicked:

def update(model, %WidgetEvent{type: :sort, id: "users", data: %{column: col}}) do
  dir = if model.sort_by == col and model.sort_order == :asc, do: :desc, else: :asc
  %{model | sort_by: col, sort_order: dir}
end

The table itself does not sort. It displays rows in the order you provide. Sort in your model or use Plushie.Data.query/2.

Interaction wrappers

pointer_area

Wraps a single child and captures pointer events from mouse, touch, and pen input. Use for right-click menus, hover detection, drag tracking, scroll capture, and custom cursor styles. All events use the unified pointer model: the pointer field (:mouse, :touch, :pen) identifies the device, and modifiers carries the current modifier key state for shift-click, ctrl-drag, and similar patterns.

Cursor values: :pointer, :grab, :grabbing, :crosshair, :text, :move, :not_allowed, :progress, :wait, :help, :resizing_horizontally, :resizing_vertically, and others.

Move and scroll events carry pointer (device type) and modifiers (current modifier key state):

pointer_area "canvas-area",
  on_move: true,
  on_press: :area_press,
  on_scroll: true,
  cursor: :crosshair do
  canvas "drawing", width: 400, height: 300 do
    # ...
  end
end

# Shift-click for multi-select
def update(model, %WidgetEvent{type: :press, id: "canvas-area",
    data: %{pointer: :mouse, modifiers: %{shift: true}}}) do
  add_to_selection(model)
end

# Ctrl-drag for panning
def update(model, %WidgetEvent{type: :move, id: "canvas-area",
    data: %{x: x, y: y, modifiers: %{ctrl: true}}}) do
  pan_canvas(model, x, y)
end

# Scroll with pointer type
def update(model, %WidgetEvent{type: :scroll, id: "canvas-area",
    data: %{delta_y: dy, pointer: :mouse}}) do
  zoom(model, dy)
end

sensor

Wraps a single child and emits events when the child's size changes or when it enters/exits visibility. Useful for responsive layouts, lazy loading, and intersection observation.

Events: :resize with %{width: w, height: h} in data.

overlay

Positions the second child as a floating overlay relative to the first child (anchor). Exactly two children required.

The overlay renders above all other content at the positioned location. See the Composition Patterns reference for a popover menu example.

themer

Applies a different theme to its children. Single child, single prop:

themer "dark-section", theme: :dark do
  container padding: 12 do
    text("info", "This section uses the dark theme")
  end
end

Common props

Most widgets support a subset of these cross-cutting props:

• :style - visual appearance. Accepts a preset atom (e.g. :primary, :danger) or a StyleMap. See the Styling reference.
• :a11y - accessibility attributes. See the Accessibility reference.
• :width / :height - sizing. Accepts :fill, :shrink, {:fill_portion, n}, or a pixel number. See the Layout reference.
• :event_rate - max events per second for high-frequency events. Supported on slider, vertical_slider, pointer_area, sensor, canvas, and pane_grid.

Renderer-side state

Some widgets hold state in the renderer that persists across re-renders. If their ID changes, this state resets:

• text_input - cursor position, selection, undo history
• text_editor - cursor, selection, scroll position, undo
• combo_box - search text, open/closed state
• scrollable - scroll position
• pane_grid - pane sizes and arrangement

These widgets require explicit string IDs. scrollable and pane_grid produce compile-time errors if you forget the ID.

keyed_column vs column

Use column for static layouts. Use keyed_column when children are dynamic (added, removed, reordered). It diffs by child ID instead of position, preserving widget state across list changes. Same props as column minus align_x, clip, and wrap.

Auto-ID vs explicit ID

Layout containers (column, row, stack, grid, keyed_column, responsive) and some display widgets (text, markdown, rule, space, progress_bar) support auto-generated IDs. Omit the ID and one is generated from the call site.

All interactive and stateful widgets require explicit string IDs for event routing and state persistence. See the DSL reference for the full breakdown.

Animatable props

Numeric props support renderer-side transitions via transition(), spring(), and loop(). Commonly animated: max_width, max_height, opacity, translate_x, translate_y, scale. See the Animation reference.

Prop value types

These prop types are used across multiple widgets. The full styling types (Color, Theme, StyleMap, Border, Shadow, Gradient) are in the Styling reference. Layout types (Length, Padding, Alignment) are in the Layout reference.

Font

Used by: text, rich_text, text_input, text_editor.

The full font spec struct (Plushie.Type.Font) also supports weight: (:thin through :black), style: (:normal, :italic, :oblique), and stretch: (:ultra_condensed through :ultra_expanded).

Shaping

Used by: text, rich_text, text_input, text_editor.

Wrapping

Used by: text, rich_text.

Content fit

Used by: image, svg.

Filter method

Used by: image.

Tooltip position

Used by: tooltip.

Scroll direction

Used by: scrollable.

Scroll anchor

Used by: scrollable.

See also

• Layout reference - sizing, alignment, and all layout containers with full prop tables
• Styling reference - Color, Theme, StyleMap, Border, Shadow, Gradient
• Canvas reference - shapes, layers, interactive groups
• Accessibility reference - the a11y prop, roles, and keyboard navigation
• Events reference - all event types delivered by widgets
• DSL reference - three forms, auto-IDs, compile-time validation
• Animation reference - transition, spring, loop descriptors
• Layout guide - layout applied to the pad
• Styling guide - themes and visual customization