# Canvas
Canvas is a different paradigm from the widget tree. Instead of composing
layout containers and input widgets, you draw shapes on a 2D surface:
rectangles, circles, lines, paths, and text. Shapes can be grouped into
interactive elements with click handlers, hover effects, and accessibility
annotations.
In this chapter we will learn canvas by building a **custom save button** --
a styled, interactive canvas widget that replaces the plain `button("save")`
in the pad. Along the way we will cover shapes, interactive groups, style
overrides, and how canvas composes with the rest of the widget tree.
## Shapes
All shapes are plain function calls that return typed structs. They live
inside `layer` blocks within a canvas. Note that `text`, `image`, and `svg`
automatically resolve to their canvas shape variants inside canvas blocks --
the compiler handles this, so you use the same names without qualification.
Variables assigned in one line of a layer or group block are visible in
subsequent lines. Standard Elixir scoping rules apply:
```elixir
canvas "demo", width: 200, height: 100 do
layer "bg" do
bg_fill = "#f0f0f0"
rect(0, 0, 200, 100, fill: bg_fill, radius: 8)
circle(100, 50, 20, fill: "#3b82f6")
line(10, 90, 190, 90, stroke: stroke("#ccc", 1))
text(100, 50, "Hello", fill: "#333", size: 14)
end
end
```
`rect` draws a rectangle, `circle` a circle, `line` a line segment, and
`text` renders text at a position. Each accepts optional `fill`, `stroke`,
and `opacity`.
### Strokes
The `stroke/3` helper creates stroke descriptors:
```elixir
stroke("#333", 2) # colour and width
stroke("#333", 2, cap: :round) # with line cap
stroke("#333", 2, dash: {[5, 3], 0}) # dashed line
```
Shape do-blocks support nested Buildable types, so you can declare
stroke options inline:
```elixir
rect(0, 0, 100, 50) do
fill "#3b82f6"
radius 6
stroke do
color "#333"
width 2
cap :round
end
end
```
### Gradients
`linear_gradient/3` creates a gradient for use as a fill:
```elixir
rect(0, 0, 100, 36,
fill: linear_gradient({0, 0}, {100, 0}, [
{0.0, "#3b82f6"},
{1.0, "#1d4ed8"}
]),
radius: 6
)
```
### Paths
For arbitrary shapes, use `path/2` with a list of commands:
```elixir
path([
move_to(10, 0),
line_to(20, 20),
line_to(0, 20),
close()
], fill: "#22c55e")
```
See the [Canvas reference](../reference/canvas.md) for the full list of
path commands (`bezier_to`, `quadratic_to`, `arc`, `arc_to`, `ellipse`,
`rounded_rect`).
## SVG and images
For complex visuals, you can embed SVG content directly in a canvas layer.
Design your icons, illustrations, or controls in a vector editor (Figma,
Inkscape, Illustrator), export to SVG, and render them at any position and
size:
```elixir
layer "icons" do
svg(File.read!("priv/icons/save.svg"), 10, 8, 20, 20)
end
```
The first argument is the SVG source string. Combined with interactive
groups, this lets you build fully custom controls from externally designed
assets:
```elixir
group "save", on_click: true, cursor: :pointer do
svg(File.read!("priv/icons/save.svg"), 0, 0, 36, 36)
end
```
`image/5` works the same way for raster images (PNG, JPEG). SVG is
generally preferred for UI elements because it scales without pixelation.
## Interactive groups
Groups become interactive when you add event props. This is where canvas
gets powerful. You can make any collection of shapes clickable, hoverable,
or draggable:
```elixir
group "my-btn", on_click: true, on_hover: true, cursor: :pointer do
rect(0, 0, 100, 36, fill: "#3b82f6", radius: 6)
text(50, 11, "Click me", fill: "#fff", size: 14)
end
```
### Hover and press styles
`hover_style` and `pressed_style` change the visual appearance during
interaction. No event handling needed; the renderer applies them
automatically:
```elixir
group "my-btn",
on_click: true,
cursor: :pointer,
hover_style: %{fill: "#2563eb"},
pressed_style: %{fill: "#1d4ed8"} do
rect(0, 0, 100, 36, fill: "#3b82f6", radius: 6)
text(50, 11, "Save", fill: "#fff", size: 14)
end
```
On hover, the rectangle fill shifts to a darker blue. On press, it gets
darker still. The text stays white because the style override only affects
the properties you specify.
### Accessibility
Built-in widgets like `button` and `text_input` have accessibility roles
and labels built in (a button announces itself as a button automatically).
Canvas is a raw drawing surface, so the renderer has no way to know that
a group of shapes is meant to be a "button." You tell it with `a11y`
annotations:
```elixir
group "save-btn",
on_click: true,
cursor: :pointer,
focusable: true,
a11y: %{role: :button, label: "Save experiment"} do
# shapes...
end
```
`focusable: true` allows keyboard navigation (Tab to focus, Space/Enter to
activate). The `a11y` map provides the role and label for screen readers.
See the [Accessibility reference](../reference/accessibility.md) for the
full set of available annotations.
## Building the save button
Let us put it all together. Here is a custom save button with a gradient
fill, rounded corners, hover/press feedback, and accessibility:
```elixir
defp save_button do
canvas "save-canvas", width: 100, height: 36 do
layer "button" do
group "save",
on_click: true,
cursor: :pointer,
focusable: true,
a11y: %{role: :button, label: "Save experiment"},
hover_style: %{fill: "#2563eb"},
pressed_style: %{fill: "#1d4ed8"} do
rect(0, 0, 100, 36,
fill: linear_gradient({0, 0}, {100, 0}, [
{0.0, "#3b82f6"},
{1.0, "#2563eb"}
]),
radius: 6
)
text(50, 11, "Save", fill: "#ffffff", size: 14)
end
end
end
end
```
### Applying it: replace the plain save button
In the pad's view, replace `button("save", "Save")` with the canvas
version:
```elixir
row padding: 4, spacing: 8 do
save_button()
checkbox("auto-save", model.auto_save)
text("auto-label", "Auto-save")
end
```
The canvas button emits a regular `:click` event with the canvas ID in scope.
Update the save handler to match:
```elixir
def update(model, %WidgetEvent{type: :click, id: "save", scope: ["save-canvas" | _]}) do
case compile_preview(model.source) do
{:ok, tree} ->
if model.active_file, do: save_experiment(model.active_file, model.source)
%{model | preview: tree, error: nil}
{:error, msg} ->
%{model | error: msg, preview: nil}
end
end
```
The `id` is `"save"` (the group ID), and it arrives with
`scope: ["save-canvas", window_id]`. You can match on scope to
disambiguate canvas element clicks from regular widget clicks with
the same ID.
You now have a custom-drawn, gradient-filled, hover-responsive save button
in your pad. This is the same technique you would use to build custom
controls, charts, diagrams, or any visual element that goes beyond the
built-in widgets.
## Layers
Layers control drawing order. Earlier layers are behind, later layers are
on top:
```elixir
canvas "layered", width: 200, height: 100 do
layer "background" do
rect(0, 0, 200, 100, fill: "#f5f5f5")
end
layer "foreground" do
circle(100, 50, 30, fill: "#3b82f6")
end
end
```
## Transforms and clips
Transforms apply to **groups**, not individual shapes. Three transforms are
available: `translate/2`, `rotate/1` (degrees by default), and `scale/1`
or `scale/2`.
```elixir
group x: 100, y: 50 do
rotate(45)
rect(0, 0, 40, 40, fill: "#ef4444")
end
```
`rotate/1` accepts degrees by default. For explicit units, use keyword
form: `rotate(degrees: 45)` or `rotate(radians: 0.785)`.
The `x:` and `y:` shorthand desugars to a leading `translate`.
`clip/4` restricts drawing to a rectangular region (one per group):
```elixir
group do
clip(0, 0, 80, 80)
circle(40, 40, 60, fill: "#3b82f6")
end
```
## Canvas events
Canvas events arrive as `Plushie.Event.WidgetEvent` structs:
**Canvas-level** (requires `on_press`/`on_release`/`on_move`/`on_scroll`
on the canvas). These use the unified pointer event model. Mouse, touch,
and pen input all produce the same event types. The `pointer` field
identifies the device, and `finger` carries the touch finger ID:
```elixir
# Mouse click
%WidgetEvent{type: :press, data: %{x: 150.0, y: 75.0, button: :left, pointer: :mouse, modifiers: %KeyModifiers{}}}
# Touch press
%WidgetEvent{type: :press, data: %{x: 150.0, y: 75.0, button: :left, pointer: :touch, finger: 0, modifiers: %KeyModifiers{}}}
```
**Element-level** (requires `on_click`/`on_hover`/`draggable` on the
group):
```elixir
%WidgetEvent{type: :click, id: "save", scope: ["save-canvas", "main"], window_id: "main"}
%WidgetEvent{type: :enter, id: "save", scope: ["save-canvas", "main"], window_id: "main"}
%WidgetEvent{type: :exit, id: "save", scope: ["save-canvas", "main"], window_id: "main"}
```
See the [Canvas reference](../reference/canvas.md) for the full event list.
## Composing canvas with widgets
Canvas is just another widget in the tree. It composes with layout
containers like anything else:
```elixir
column do
row spacing: 8 do
save_button() # canvas widget
button("clear", "Clear") # regular widget
end
canvas "chart", width: :fill, height: 200 do
# ...
end
end
```
Mix canvas and regular widgets freely. Use canvas when you need custom
visuals; use widgets for standard controls.
## Verify it
Test the canvas save button, including its accessibility annotations:
```elixir
test "canvas save button works and has correct a11y" do
click("#save-canvas/save")
assert_text("#preview/greeting", "Hello, Plushie!")
assert_role("#save-canvas/save", "button")
assert_a11y("#save-canvas/save", %{label: "Save experiment"})
end
```
This exercises the canvas click event, verifies compilation still works,
and confirms the accessibility annotations are present on the canvas
element, something that built-in widgets provide automatically but
canvas elements need explicitly.
## Try it
Write canvas experiments in your pad:
- Draw a few shapes: rectangles with gradients, circles with strokes,
dashed lines.
- Build a bar chart: for each data point, draw a `rect` with height
proportional to the value. Add `tooltip:` for hover labels.
- Create a path: draw a triangle, a star, or a curved shape.
- Add an interactive group with `on_hover: true` and `hover_style`. Watch
the element highlight when you mouse over it.
- Try transforms: rotate a group, clip a shape to a smaller region.
The [Canvas reference](../reference/canvas.md) has the complete shape
catalog, all path commands, and full interactive group props.
In the next chapter, we will extract reusable components from the pad as
custom widgets.
---
Next: [Custom Widgets](13-custom-widgets.md)
