# Custom Widgets
As the pad has grown, the view function has gotten larger. The file list,
event log, and preview pane are each self-contained pieces of UI with their
own rendering logic. In this chapter we extract them into **custom widgets**
-- reusable modules that encapsulate UI and behaviour.
Plushie has two kinds of custom widgets: pure Elixir (compose existing
widgets or draw custom visuals with canvas and SVG) and native (Rust-backed,
for custom GPU rendering). This chapter covers pure Elixir widgets. Native
widgets get a brief section at the end, with full details in the
[Custom Widgets reference](../reference/custom-widgets.md).
## Stateless widgets
The simplest custom widget is stateless: it takes props, returns a UI tree,
and has no internal state. Events from widgets inside it pass through
transparently to the parent app.
```elixir
defmodule PlushiePad.LabeledInput do
use Plushie.Widget
widget :labeled_input
prop :label, :string
prop :value, :string
prop :placeholder, :string, default: ""
def view(id, props) do
import Plushie.UI
column id: id, spacing: 4 do
text(props.label, size: 12)
text_input("input", props.value, placeholder: props.placeholder)
end
end
end
```
`use Plushie.Widget` generates a struct, a `new/2` constructor, setter
functions, and the protocol implementation that connects it to the rendering
pipeline.
`widget :labeled_input` declares the widget's type name. This must be unique
across your application. It is used for event namespacing and protocol
dispatch.
`prop` declarations define typed properties with optional defaults. Available
types include `:string`, `:number`, `:boolean`, `:color`, `:length`,
`:padding`, `:font`, `:atom`, `:map`, `:any`, and others. See
`Plushie.Widget` for the full list.
`view/2` receives the widget ID and a props map. It returns a UI tree using
the same DSL as `view/1`. Events from widgets inside (like the `text_input`)
flow through to the parent app's `update/2` without any special handling.
Use it in a view:
```elixir
PlushiePad.LabeledInput.new("email",
label: "Email",
value: model.email,
placeholder: "you@example.com"
)
```
### Applying it: extract FileList
The file list sidebar is a good candidate. It takes the files list and
active file, renders the sidebar, and events (select, delete) pass through
to the pad's `update/2`:
```elixir
defmodule PlushiePad.FileList do
use Plushie.Widget
widget :file_list
prop :files, :any # list of filenames
prop :active_file, :any # currently selected filename
def view(id, props) do
import Plushie.UI
column id: id, width: 200, height: :fill, padding: 8, spacing: 8 do
text("sidebar-title", "Experiments", size: 14)
scrollable "file-scroll", height: :fill do
keyed_column spacing: 2 do
for file <- props.files do
container file do
row spacing: 4 do
button("select", file,
width: :fill,
style: if(file == props.active_file, do: :primary, else: :text)
)
button("delete", "x")
end
end
end
end
end
end
end
end
```
In the pad's view:
```elixir
PlushiePad.FileList.new("sidebar",
files: model.files,
active_file: model.active_file
)
```
The pad's `update/2` still handles the select and delete events via scoped
IDs. The widget is transparent to events.
## Stateful widgets
When a widget needs internal state that the parent app should not manage,
add `state` declarations and a three-argument `view/3`:
```elixir
defmodule PlushiePad.CollapsiblePanel do
use Plushie.Widget
widget :collapsible_panel, container: true
prop :title, :string
state expanded: true
@impl Plushie.Widget.Handler
def view(id, props, state) do
import Plushie.UI
column id: id, spacing: 4 do
button("toggle", if(state.expanded, do: "- #{props.title}", else: "+ #{props.title}"))
if state.expanded do
container "content", padding: 8 do
props.children
end
end
end
end
@impl Plushie.Widget.Handler
def handle_event(%Plushie.Event.WidgetEvent{type: :click, id: "toggle"}, state) do
{:update_state, %{state | expanded: not state.expanded}}
end
def handle_event(_event, _state), do: :ignored
end
```
`state expanded: true` declares internal state with a default value. The
runtime manages this state. It persists across re-renders as long as the
widget remains in the tree.
`view/3` receives the ID, props, and current state.
`container: true` on the widget declaration allows the widget to accept
children via `props.children`.
## Handling events
The `handle_event/2` callback intercepts events before they reach the parent
app. All clauses must return one of:
| Return value | Effect |
|---|---|
| `{:emit, family, data}` | Emit a new event to the parent. Original is replaced. |
| `{:emit, family, data, new_state}` | Emit to parent and update internal state. |
| `{:update_state, new_state}` | Update internal state. No event reaches the parent. |
| `:consumed` | Suppress the event. Nothing reaches the parent. |
| `:ignored` | Pass through. The event continues to the parent unchanged. |
Events walk up the widget scope chain. If a widget returns `:ignored`, the
next widget handler in the chain gets a chance. If no handler captures the
event, it reaches `update/2`.
### Applying it: extract EventLog
The event log can track its own expanded/collapsed state:
```elixir
defmodule PlushiePad.EventLog do
use Plushie.Widget
widget :event_log
prop :events, :any # list of event description strings
state expanded: true
@impl Plushie.Widget.Handler
def view(id, props, state) do
import Plushie.UI
column id: id, spacing: 4 do
row spacing: 8 do
button("toggle-log", if(state.expanded, do: "Hide Log", else: "Show Log"))
text("count", "#{length(props.events)} events", size: 12)
end
if state.expanded do
scrollable "log-scroll", height: 120 do
column spacing: 2, padding: 4 do
for {entry, i} <- Enum.with_index(props.events) do
text("log-#{i}", entry, size: 12, font: :monospace)
end
end
end
end
end
end
@impl Plushie.Widget.Handler
def handle_event(%Plushie.Event.WidgetEvent{type: :click, id: "toggle-log"}, state) do
{:update_state, %{state | expanded: not state.expanded}}
end
def handle_event(_event, _state), do: :ignored
end
```
The toggle button updates the widget's internal state. All other events
(from the log entries, if any were interactive) pass through via `:ignored`.
## Declaring events
When a widget should emit semantic events to the parent, declare them with
`event`:
```elixir
defmodule PlushiePad.RatingWidget do
use Plushie.Widget
widget :rating
prop :value, :number, default: 0
event :change, value: :number
@impl Plushie.Widget.Handler
def view(id, props, _state) do
import Plushie.UI
row id: id, spacing: 4 do
for i <- 1..5 do
button("star-#{i}", if(i <= props.value, do: "★", else: "☆"))
end
end
end
@impl Plushie.Widget.Handler
def handle_event(%Plushie.Event.WidgetEvent{type: :click, id: "star-" <> n}, _state) do
{:emit, :change, String.to_integer(n)}
end
def handle_event(_event, _state), do: :ignored
end
```
The `event :change, value: :number` declaration tells the framework that
this widget emits `:change` events with a numeric value. In the parent app,
these arrive as:
```elixir
%WidgetEvent{type: {:rating, :change}, id: "my-rating", value: 3}
```
Custom widget event types are tuples: `{widget_type, event_name}`. This
distinguishes them from built-in events.
For events with multiple fields, use `data:` instead of `value:`:
```elixir
event :change, data: [hue: :number, saturation: :number, value: :number]
```
These arrive in `WidgetEvent.data` as an atom-keyed map.
## Widget subscriptions
Widgets can declare their own subscriptions via the optional `subscribe/2`
callback:
```elixir
@impl Plushie.Widget.Handler
def subscribe(_props, state) do
if state.animating do
[Plushie.Subscription.every(16, :animate)]
end
end
```
Widget subscriptions are automatically namespaced per instance. Timer events
are routed through the widget's `handle_event/2`, not the app's `update/2`.
Multiple instances of the same widget each get independent subscriptions.
## Canvas-based widgets
A widget's `view/2` can return a canvas instead of layout widgets:
```elixir
defmodule PlushiePad.Gauge do
use Plushie.Widget
widget :gauge
prop :value, :number, default: 0
prop :max, :number, default: 100
@impl Plushie.Widget.Handler
def view(id, props, _state) do
import Plushie.UI
pct = min(props.value / props.max, 1.0)
angle = pct * :math.pi()
canvas id, width: 120, height: 70 do
layer "gauge" do
# Background arc
path([arc(60, 60, 50, :math.pi(), 0)],
stroke: stroke("#ddd", 8, cap: :round)
)
# Value arc
path([arc(60, 60, 50, :math.pi(), :math.pi() + angle)],
stroke: stroke("#3b82f6", 8, cap: :round)
)
# Value text
text(40, 55, "#{round(pct * 100)}%", fill: "#333", size: 16)
end
end
end
end
```
Canvas-based widgets with interactivity combine `handle_event/2` with
canvas events (`:press`, `:enter`, `:drag`, etc.) to build
rich custom controls like colour pickers, drawing tools, and data
visualisations. You can also embed SVG content in canvas layers (as
shown in [chapter 12](12-canvas.md)). Design your visuals in a vector
editor and use them as interactive widget elements.
## The widget lifecycle
Understanding the lifecycle helps when debugging:
1. Your view calls `MyWidget.new(id, opts)`, which returns a widget struct.
2. During tree normalization, the struct is converted to a placeholder node
tagged with the widget module and props.
3. The runtime detects the placeholder, looks up stored state (or uses
initial defaults for new widgets), and calls `view/3`.
4. The rendered output replaces the placeholder in the final tree.
5. Widget metadata (module, state, event handlers) is attached to the
node's `:meta` field.
6. The runtime derives a handler registry from the tree for event dispatch.
There are no explicit mount or unmount callbacks. **Tree presence is the
lifecycle.** When a widget appears in the tree, it is "mounted" with initial
state. When it disappears, its state is cleaned up. This is why widget IDs
must be stable. A changing ID looks like a removal and re-creation.
## Native widgets
When you need rendering capabilities beyond what built-in widgets offer --
custom GPU drawing, new input types, or performance-critical visuals, you
can build a **native widget** backed by Rust:
```elixir
defmodule MyApp.Gauge do
use Plushie.Widget, :native_widget
widget :gauge
prop :value, :number
rust_crate "path/to/gauge_crate"
rust_constructor "gauge::new()"
end
```
On the Rust side, you implement the `WidgetExtension` trait with `render()`,
and optionally `init()`, `prepare()`, `handle_event()`, and `cleanup()`.
`mix plushie.build` auto-detects native widgets via protocol consolidation,
generates a Cargo workspace that includes them, and builds the renderer
binary with your widgets registered.
Native widgets are an escape hatch for when pure Elixir composition is not
enough. Most apps will never need them. See the
[Custom Widgets reference](../reference/custom-widgets.md) for the full Rust
integration guide.
## Verify it
Test the EventLog widget using `Plushie.Test.WidgetCase`:
```elixir
defmodule PlushiePad.EventLogTest do
use Plushie.Test.WidgetCase, widget: PlushiePad.EventLog
setup do
init_widget("log", events: ["click on btn", "input on name"])
end
test "shows event entries" do
element = find!({:text, "click on btn"})
assert element.type == "text"
end
end
```
`WidgetCase` hosts a single widget in a test harness. The `init_widget/2`
call creates the widget with the given props. This is covered in detail in
[chapter 15](15-testing.md).
## Try it
Build custom widgets in your pad experiments:
- Start with a stateless widget that composes a label and an input. Use it
in another experiment.
- Add `state` and `handle_event/2` to make a collapsible section.
- Declare a custom event and match on the `{widget_type, :event_name}` tuple
in the parent experiment.
- Build a canvas-based widget: a simple progress ring, a mini sparkline, or
a colour swatch.
- Try a widget with `subscribe/2` that animates on a timer.
In the next chapter, we will enhance the pad with state management helpers
for undo, search, selection, and navigation.
---
Next: [State Management](14-state-management.md)
