When to use it. A heading-driven action ring. The device's live heading rotates a needle; you arrange action pucks around the ring; when the needle points at a puck (within tolerance) for dwell seconds, that puck's action fires. Point your phone at a thing to trigger it — no tapping. Pucks can be dragged around the ring to re-bearing them (firing pickup/place/layout), so the same control authors and runs.
Type
compass
Also titled
Compass
Default size
7 rows × 3 columns
Symbol
location.north.circle.fill
Docs
Docs complete
Search for it as
heading
direction
bearing
north
orientation
navigation
Rendered by the app
Fields
11 fields you can set on a compass control. Every control also takes the shared fields (id, position, span, sync, action).
Fields
Field
Type
Default
What it does
haptichaptic
choiceone of 10
—
Buzz when you use the ring
Plays this haptic when a puck is picked up, dropped or fires; the action firing uses medium when not set.
noneno haptic
lighta small light tap
mediuma medium tap and the default for firing
heavya strong tap
softa rounded cushioned tap
rigida sharp firm tap
selectiona tiny tick like scrolling a picker
successa success pattern
warninga warning pattern
erroran error pattern
Labellabel
text
—
Title above the ring
Shows this text as the title above the ring.
HeightcontrolHeight
number100–1200step 10
420
How tall the ring is
Sets the ring's height in points, which also sets its size since it is square.
TolerancecompassConfig.tolerance
number1–90step 1
15
How close the needle must aim
Counts the needle as pointing at a puck when it is within this many degrees of it.
Hold timecompassConfig.dwell
number0–10step 0.1
1.2
How long to hold aim
Waits this many seconds of steady aim at a puck before its action fires; 0 fires at once.
LetterscompassConfig.showCardinals
on / off
true(on)
Show the N E S W letters
Draws the N, E, S and W letters around the ring when on.
Letter sizecompassConfig.cardinalSize
number8–40step 1
13
Size of the compass letters
Sets the size of the N, E, S and W letters in points.
Letter colorcompassConfig.cardinalColor
color
—
Color of the compass letters
Colors the N, E, S and W letters; they use a neutral grey when not set.
EditablecompassConfig.editable
on / off
true(on)
Let people move the pucks
Lets you drag pucks around the ring to change their direction when on; off locks them all.
eventscompassConfig.events
object
—
What happens when a puck is moved
Runs these actions when a puck is picked up, dropped or the layout changes.
puckscompassConfig.pucks
object
—
The actions around the ring
Places one puck on the ring per entry at its bearing; aiming at it fires its action.
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 aim at a puckpucks
hold
id
the id of the puck you are aiming at
It sends after the needle stays within Tolerance of the puck for the Hold time; with a hold of 0 it sends at once. Each puck carries its own action
Example: Item 1
When you drop a puckplace
drop
json
the puck you dropped and its new bearing
Only when Editable is on; a layout event with every puck follows
Try it: the bundled compass-demo layout has this ring (seeded to 5° so a
needle shows in the simulator).
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 first spatial (Pattern-3) drag control: puck placements ride a bearing coordinate
(CARSpatialPlacementState) and the whole ring speaks the Toggle expand convention.
Heading (required)
The needle is driven by the control's own value — bind the compass sensor:
The bound value is the heading in degrees (0 = N, clockwise). No compass hardware (e.g.
the simulator)? Set a defaultValue (a number) to render a static needle for testing.
Sizing
Square control. In a mode: "flow" grid set controlHeight (e.g. 420); in a 2-D grid
give it a real span. See Grid Dimensions.
Config (compassConfig)
Field
Type
Description
pucks
array
The action pucks (below).
tolerance
number
Half-angle (°) the needle must be within to "point at" a puck (default 15).
dwell
number
Seconds to hold before firing (default 1.2; 0 = instant on entry).
Fired on point-and-dwell. {{value}} = the puck id.
locked
bool
Can't be dragged (still activatable).
Events
Puck drag fires place{ item, x, y, bearing } and layout{ points: { id: {x,y,bearing} }, changed } (see DragEventActions). Puck
activation fires that puck's own action.
Accessibility
Under VoiceOver each puck reads its bearing, double-tap fires its action (no
pointing needed), and the adjustable action (swipe up/down) rotates it 15° per step.