When to use it. A searchable option area plus one or more bound placement zones you drag items between — a kanban board, a triage inbox, a seating chart, a tier list. Each item lives in exactly one place at a time. On every drop the board fires up to three events and writes the whole arrangement back through its synced value, so a server can seed the initial layout or push a new one in the same shape.
Type
sortboard
Also titled
Sortboard
Default size
10 rows × 4 columns
Symbol
rectangle.3.group.fill
Docs
Docs complete
Search for it as
kanban
drag
reorder
sort
buckets
ranking
Rendered by the app
Fields
11 fields you can set on a sortboard 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 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.
SearchsortboardConfig.searchable
on / off
false(off)
A search box over the cards
Adds a filter field above the option area so you can find an item by its label.
Palette titlesortboardConfig.paletteLabel
text
Options
The name of the card pile
Sets the header over the option area, e.g. Backlog instead of Options.
PalettesortboardConfig.hidePalette
on / off
false(off)
Hide the card pile
Removes the option area so only the columns show, for boards whose items all start placed.
ColumnssortboardConfig.columns
number1–12step 1
2
How many columns
Lays the zones out in this many columns side by side, 1 to 12.
eventssortboardConfig.events
object
—
What happens when you drag
Holds the pickup, place and layout actions that fire as you lift, drop and settle a card.
itemssortboardConfig.items
object
—
The cards you can move
Lists the cards, each with an id, label, icon, tint, optional starting zone and a locked flag.
zonessortboardConfig.zones
object
—
The columns cards go into
Lists the zones, each with an id, label, tint and optional accepts, capacity and locked limits.
sortboardConfigsortboardConfig
object
—
The board settings in one bundle
Groups the search, palette, columns, events, items and zones 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 cardpickup
lift
id
the lifted card's id
The options area has the column id palette
Example: item-1
When you drop a cardplace
drop
id
the dropped card's id
Example: item-1
When the board settleslayout
settle
json
every column's cards in order, plus the move that just happened
Keys you add to this action's payload are sent along with the arrangement
A broadcast whose state is { "zones": { "primary": ["sam"], "backup": ["riley"] } }
seats everyone from the server.
Rendered by the app
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.
Drag is instant — touch a chip and it lifts and follows your finger right away
(no long-press wait). A grip glyph marks what's moveable; a locked item or zone
shows a lock badge, stays put, and rejects drops. Dropping between chips inserts by
position; dropping into empty space appends.
Sizing (read this first)
The board manages its own internal scrolling, so it needs a real height or it
collapses to one row. Two ways, matching the grid's mode:
mode: "flow" grid → set controlHeight (e.g. 560). This is the simplest
and what the bundled demo uses.
mode: "grid"/2-D grid → give it a real span rowSpan (e.g. [9, 4]);
controlHeight is ignored in 2-D. See Grid Dimensions.
Config (sortboardConfig)
Field
Type
Description
items
array
The option catalog. Each: { id, label?, icon?, tint?, zone?, locked? }. zone pre-places an item in that zone id (omitted ⇒ option area); locked: true pins it — it shows a lock badge and can't be dragged.
zones
array
The bins. Each: { id, label?, tint?, accepts?, capacity?, locked? }. accepts is a list of item ids the zone allows (omitted ⇒ any); capacity caps the count; locked: true fixes the whole column (nothing moves in or out).
searchable
bool
Filter field above the option area.
paletteLabel
string
Header for the option area (default "Options").
hidePalette
bool
Hide the option area entirely — for boards whose items all start placed.
columns
number
Zone columns (default 2).
events
object
The pickup / place / layout actions (below).
icon is any SF Symbol name; tint is a hex string.
Events (sortboardConfig.events)
Each is a standard action definition. An author payload receives
{{item}}, {{from}}, {{to}}, {{index}} token substitution; with no payload,
the tokens are sent as a flat object.
from/to are zone ids; the reserved id "palette" is the option area.
Accessibility
Under VoiceOver each chip is its own element: it reads its label and current zone,
and exposes a named "Move to <zone>" action per eligible destination (plus
"Return to <palette>") — the full board works without drag.
Synced value
The control's value is the arrangement JSON:
{ "zones": { "<zoneId>": ["<itemId>", …] } }. Point a Sync binding at a value in
this shape to let a server rearrange the board live. Unknown ids are dropped and any
declared item the server omits is parked back in the option area, so nothing silently
disappears.
Related
Toggle expand — Action definition and payload tokens