When to use it. A freeform container: real, live controls hosted at normalized (x, y, w, h) on a pannable, zoomable surface. Where Palette places markers, canvas places whole working controls — each card renders through the real renderer, so its bindings, actions, sync and theming all work exactly as they would in a grid cell.
Type
canvas
Also titled
Canvas
Default size
10 rows × 4 columns
Symbol
square.on.square.dashed
Docs
Docs complete
Search for it as
draw
drawing
sketch
paint
shapes
freeform
Rendered by the app
Fields
10 fields you can set on a canvas control. Every control also takes the shared fields (id, position, span, sync, action).
Fields
Field
Type
Default
What it does
haptichaptic
choiceone of 10
—
The buzz you feel on a lift
Plays this haptic on the phone when you long-press and lift a card.
noneno vibration
lighta small soft tap
mediuma medium tap
heavya strong thud
softa muted cushioned bump
rigida firm sharp click
selectionthe faint tick of picking an item
successthe double tap of a success
warninga two-pulse warning
errora sharp triple buzz of an error
Labellabel
text
—
The name shown with the canvas
Shows this text as the canvas header label.
HeightcontrolHeight
number100–1200step 10
560
How tall the canvas is
Sets the rendered height of the surface in points.
ShapecanvasConfig.aspect
number0.2–5step 0.1
1.0
How wide versus tall the surface is
Reshapes the surface to this width-to-height ratio, fitted inside the available space.
EditablecanvasConfig.editable
on / off
false(off)
Touch and hold a card to move it
Lets you long-press a card to lift and drag it, firing place and layout actions on drop.
GridcanvasConfig.showGrid
on / off
false(off)
Dots to line things up
Draws a faint dot lattice on the surface, spaced by the snap step when set.
SnapcanvasConfig.snap
number0–1step 0.05
0
Snap cards to a grid
Rounds a dropped card to this fraction of the surface; 0 leaves it where you let go.
Max zoomcanvasConfig.maxZoom
number0.5–4step 0.1
3
How far you can pinch in
Caps how far a pinch can zoom the surface; 1 turns zoom and panning off.
itemscanvasConfig.items
list
—
The cards on the board
Places each listed control on the surface at its own position and size, later ones on top.
eventscanvasConfig.events
object
—
What happens when you move a card
Runs the pickup, place and layout actions as a card is lifted and dropped.
Emits and receives
What this control sends when you use it, and what it can show or follow when data arrives.
Emits
Emits
Sends
When
Type
What it sends
When you drop a cardplace
drop
json
the card you dropped and its new position and size
Only when Editable is on; a layout event with every card's frame follows, and lifting a card sends a pickup first
Try it: the bundled canvas-demo layout has both — a live status board and
an editable, snapping war-room board.
Try it
These examples need more room than carterkit demo gives one control, so paste one into a layout instead. carterkit prints this page's fields in your terminal.
Pinch to zoom (up to maxZoom), drag empty surface to pan while zoomed. With
editable: true, long-press lifts a card (so hosted controls keep their own
taps/drags), dragging moves it, and dropping emits place + layout and round-trips
the synced value — a server or a peer can seed or rearrange the board.
The structural (Pattern-7) drag control; the on-device Layout Editor speaks the
same lift/snap language but authors real grid layouts.
Sizing
In a mode: "flow" grid set controlHeight (e.g. 560); in a 2-D grid give it a real
span (rough guide: [10, 4]). aspect shapes the surface itself. See
Grid Dimensions.
Config (canvasConfig)
Field
Type
Description
items
array
The hosted controls (below). Order is z-order: later items draw on top.
aspect
number
Surface width ÷ height (default 1.0).
editable
bool
Allow rearranging cards (default false — a static freeform dashboard).
showGrid
bool
Faint dot lattice (spatial affordance for editable boards).
Max pinch-zoom scale (default 3; 1 disables zoom/pan).
events
object
pickup / place / layout fired on drag (see DragEventActions).
Item { id, x, y, w, h, locked?, control }
Field
Type
Description
id
string
Stable card id — the key in the synced frames and in events.
x, y
number
Top-leading corner, 0…1 fractions of the surface.
w, h
number
Size, 0…1 fractions of the surface (default 0.25 each).
locked
bool
Card can't be moved in editable mode (still live/interactive).
control
object
Any control object. position may be omitted (it's meaningless on a canvas).
Events
Lifting a card fires pickup{ item, from: "canvas" }. Dropping (or a VoiceOver
nudge) fires place{ item, x, y, w, h } and layout{ frames: { id: {x,y,w,h} }, changed }. Token substitution ({{item}}, {{x}}, …)
works as in every drag control.
Accessibility
Cards keep their child elements (the hosted control stays fully usable) and expose
Move left/right/up/down actions that step by the snap increment (5% when unset) —
the whole surface works without drag.
Synced value
{ "frames": { "<id>": { "x": 0.1, "y": 0.2, "w": 0.4, "h": 0.25 } } }. Sync a
value in this shape to seed or rearrange cards; ids not in items are ignored, and
frames the push omits fall back to the item's configured spot.