When to use it. An option area plus a freeform surface you drag items onto at any (x, y) — a floor-plan device placer, a map pin board, a seating chart on a photo. Drag a palette item onto the surface to place it, drag a marker to reposition, drag it back to the palette to remove, and tap a placed marker to fire its action.
Type
pinboard
Also titled
Pinboard
Default size
10 rows × 4 columns
Symbol
mappin.and.ellipse
Docs
Docs complete
Search for it as
board
notes
sticky
pins
corkboard
cards
Rendered by the app
Fields
11 fields you can set on a pinboard 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 when you drag
Plays this haptic on the phone when you interact with the board.
noneno buzz
lighta small soft tap
mediuma medium tap
heavya strong thud
softa gentle muffled tap
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 title above the board
Shows this text as the header of the pin board.
HeightcontrolHeight
number100–1200step 10
560
How tall the board is
Sets the board height in points in a flow grid; in a 2-D grid the span sets it instead.
backgroundpinboardConfig.background
text
—
A faint picture behind the surface
Draws this SF Symbol faintly behind the surface, e.g. house.fill for a floor plan or map for a map.
ShapepinboardConfig.surfaceAspect
number0.2–5step 0.1
1.4
How wide the surface is
Sets the surface shape as width divided by height, 0.2 to 5; 1.4 is wider than tall.
SearchpinboardConfig.searchable
on / off
false(off)
A search box over the pile
Adds a filter field above the option area so you can find an item by its label.
Palette titlepinboardConfig.paletteLabel
text
Items
The name of the item pile
Sets the header over the option area, e.g. Unplaced devices instead of Items.
PalettepinboardConfig.hidePalette
on / off
false(off)
Hide the item pile
Removes the option area so only the surface shows, for boards whose markers all start placed.
eventspinboardConfig.events
object
—
What happens when you drag
Holds the pickup, place and layout actions that fire as you lift, drop and settle a marker.
itemspinboardConfig.items
object
—
The things you can pin
Lists the items, each with an id, label, icon, tint, optional starting x and y, a tap action and a locked flag.
pinboardConfigpinboardConfig
object
—
The board settings in one bundle
Groups the backdrop, shape, search, palette, events and items settings; any entry left out uses its default.
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 lift a pinpickup
lift
id
the lifted pin's id
Example: item-1
When you drop a pinplace
drop
id
the dropped pin's id
Sends when you place a new pin or move a placed one; dragging a pin back to the options area removes it and sends only the layout
Example: item-1
When the board settleslayout
settle
json
every placed pin's position, plus the move that just happened
Keys you add to this action's payload are sent along with the arrangement; a removal sends no changed part
Try it: the bundled pinboard-demo layout has this floor plan (three devices
pre-placed, two in the tray).
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.
The second spatial (Pattern-3) drag control: placements ride normalized x/y
(CARSpatialPlacementState) and round-trip through the synced value, so a server can
seed or push a layout.
Sizing
In a mode: "flow" grid set controlHeight (e.g. 560); in a 2-D grid give it a real
span. surfaceAspect controls the surface's shape. See Grid Dimensions.
Config (pinboardConfig)
Field
Type
Description
items
array
The catalog (below). An item with both x and y starts placed; otherwise it's in the option area.
background
string
SF Symbol drawn faint behind the surface (e.g. "house.fill", "map"). Omitted ⇒ a plain surface.
Initial normalized position 0…1. Both present ⇒ starts placed.
action
object
Fired when the placed marker is tapped. {{value}} = the id.
locked
bool
Can't be dragged (still tappable).
Events
Placing/moving a marker fires place{ item, x, y } and layout{ points: { id: {x,y} }, changed } (see DragEventActions). Tapping a placed marker
fires that item's action. Removing a marker (drag back to the palette) fires layout.
Accessibility
Under VoiceOver tray chips expose a "Place at center" action and markers read
their position ("28% across, 40% down"), fire on double-tap, and expose "Return
to <tray>" — the full surface works without drag.
Synced value
{ "points": { "<id>": { "x": 0.28, "y": 0.4 } } }. Sync a value in this shape to
let a server seed or rearrange placements; ids not in the catalog are ignored.