Guide / Controls / Inputs

Sort board

Drag cards between columns

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
Sort board: 1 — Sprint board (searchable kanban with a WIP limit)
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
FieldTypeDefaultWhat it does
haptichapticchoiceone 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
Labellabeltext—

The title above the board

Shows this text as the header of the board.

HeightcontrolHeightnumber100–1200step 10560

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.searchableon / offfalse (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.paletteLabeltextOptions

The name of the card pile

Sets the header over the option area, e.g. Backlog instead of Options.

PalettesortboardConfig.hidePaletteon / offfalse (off)

Hide the card pile

Removes the option area so only the columns show, for boards whose items all start placed.

ColumnssortboardConfig.columnsnumber1–12step 12

How many columns

Lays the zones out in this many columns side by side, 1 to 12.

eventssortboardConfig.eventsobject—

What happens when you drag

Holds the pickup, place and layout actions that fire as you lift, drop and settle a card.

itemssortboardConfig.itemsobject—

The cards you can move

Lists the cards, each with an id, label, icon, tint, optional starting zone and a locked flag.

zonessortboardConfig.zonesobject—

The columns cards go into

Lists the zones, each with an id, label, tint and optional accepts, capacity and locked limits.

sortboardConfigsortboardConfigobject—

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
SendsWhenTypeWhat it sends
When you lift a cardpickupliftid

the lifted card's id

The options area has the column id palette

Example: item-1

When you drop a cardplacedropid

the dropped card's id

Example: item-1

When the board settleslayoutsettlejson

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

Example: {"zones": {"palette": [], "column-1": ["item-1"]}, "changed": {"item": "item-1", "from": "palette", "to": "column-1", "index": 0}}

Receives

Receives
TakesFromTypeWhat it does
arrangementfollowhub, mqtt, http, storejson

which cards sit in which column

cards move to the columns it names; ids the board does not know are dropped and cards it leaves out go back to the options area

Example: {"zones": {"column-1": ["item-2"]}}

Sample

The placeholder value the editor shows before real data arrives.

  • {"items": [{"id": "item-1", "label": "Item 1"}, {"id": "item-2", "label": "Item 2"}, {"id": "item-3", "label": "Item 3"}], "zones": [{"id": "column-1", "label": "Column 1"}, {"id": "column-2", "label": "Column 2"}]}

Examples

3 examples, each one a control you can paste into a layout.

Try it now: the bundled sortboard-demo layout has both boards below, ready to drag. Everything here is copy-paste-ready into a mode: "flow" tab.

1 — Sprint board (searchable kanban with a WIP limit)

Demonstrates searchable, capacity on the In Progress column and place and layout events.

JSON 33 lines
{
  "type": "sortboard",
  "id": "sprint-board",
  "position": [0, 0],
  "span": [10, 4],
  "controlHeight": 560,
  "label": "Sprint Board",
  "sortboardConfig": {
    "searchable": true,
    "paletteLabel": "Backlog",
    "columns": 3,
    "items": [
      { "id": "AUTH-14", "label": "OAuth refresh", "icon": "person.badge.key.fill", "tint": "#FF9500" },
      { "id": "UI-88", "label": "Dark mode", "icon": "moon.fill", "tint": "#667eea" },
      { "id": "PERF-5", "label": "Cold start", "icon": "bolt.fill", "tint": "#FF6B6B" },
      { "id": "DOC-9", "label": "API docs", "icon": "book.fill", "tint": "#5AC8FA", "zone": "doing" },
      { "id": "BUG-72", "label": "Crash on launch", "icon": "ant.fill", "tint": "#FF3B30", "zone": "done" }
    ],
    "zones": [
      { "id": "todo", "label": "To Do" },
      { "id": "doing", "label": "In Progress", "capacity": 3, "tint": "#FF9500" },
      { "id": "done", "label": "Done", "tint": "#34C759" }
    ],
    "events": {
      "place": {
        "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
        "payload": { "target_name": "tracker", "type": "move_ticket",
                     "payload": { "ticket": "{{item}}", "column": "{{to}}", "index": "{{index}}" } }
      },
      "layout": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "board_state" } }
    }
  }
}

Open in CAR-TER

Sort board: 1 — Sprint board (searchable kanban with a WIP limit)
Rendered by the app

2 — Seating chart (`accepts` + `capacity`)

Demonstrates two tables that each hold at most two guests, with a layout event on every drop.

JSON 24 lines
{
  "type": "sortboard",
  "id": "seating-board",
  "position": [0, 0],
  "span": [10, 4],
  "controlHeight": 560,
  "label": "Table Assignments",
  "sortboardConfig": {
    "paletteLabel": "Guests",
    "columns": 2,
    "items": [
      { "id": "ada", "label": "Ada", "icon": "person.fill" },
      { "id": "linus", "label": "Linus", "icon": "person.fill" },
      { "id": "grace", "label": "Grace", "icon": "person.fill" }
    ],
    "zones": [
      { "id": "table-1", "label": "Table 1", "capacity": 2, "tint": "#667eea" },
      { "id": "table-2", "label": "Table 2", "capacity": 2, "tint": "#FF9500" }
    ],
    "events": {
      "layout": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "seating_state" } }
    }
  }
}

Open in CAR-TER

Sort board: 2 — Seating chart (`accepts` + `capacity`)
Rendered by the app

3 — Server-seeded board (no option area, driven by `sync`)

The board starts empty; the server pushes the arrangement in the synced shape and the user only rearranges between zones.

JSON 29 lines
{
  "type": "sortboard",
  "id": "duty-roster",
  "position": [0, 0],
  "span": [8, 4],
  "controlHeight": 460,
  "label": "On-Call Roster",
  "sortboardConfig": {
    "hidePalette": true,
    "columns": 2,
    "items": [
      { "id": "sam", "label": "Sam", "icon": "person.fill" },
      { "id": "riley", "label": "Riley", "icon": "person.fill" }
    ],
    "zones": [
      { "id": "primary", "label": "Primary", "capacity": 1, "tint": "#FF3B30" },
      { "id": "backup", "label": "Backup", "tint": "#34C759" }
    ],
    "events": {
      "place": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply",
                 "payload": { "target_name": "pager", "type": "assign",
                              "payload": { "who": "{{item}}", "role": "{{to}}" } } }
    }
  },
  "sync": [
    { "method": "meshsocket", "type": "listen", "event": "broadcast",
      "filter": { "kind": "roster" }, "valuePath": "state" }
  ]
}

Open in CAR-TER

A broadcast whose state is { "zones": { "primary": ["sam"], "backup": ["riley"] } } seats everyone from the server.

Sort board: 3 — Server-seeded board (no option area, driven by `sync`)
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.

  1. Install the Python kit.

    pip install carterkit
  2. Read the fields offline.

    carterkit doc sortboard

carterkit quickstart

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.

Event Fires Default payload
pickup An item is lifted / picked up { "item", "from" }
place An item is dropped into a zone { "item", "from", "to", "index" }
layout The board settles after a drop { "zones": { zoneId: [itemId…] }, "changed": {…} }

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.

Generated from ControlDocs/sortboard.md. Something unclear or missing? Tell me.