Guide / Controls / Charts

Blocks

Sizes compared as blocks

When to use it. Hierarchy as space: squarified rectangles sized by value — disk usage, budget splits, portfolio weights. The hidden edge is drill-down: tap an item with children and the map zooms into it (a back chip replaces the label, Files-app style); tap a leaf and itemAction fires with the item and its drill path, so a storage map doubles as a category picker.

Type
treemap
Also titled
Treemap
Default size
3 rows × 4 columns
Symbol
rectangle.3.group.fill
Docs
Docs complete
Search for it as
  • tree map
  • hierarchy
  • blocks
  • size
  • disk usage
  • proportion
Blocks: Storage map with drill-down
Rendered by the app

Fields

13 fields you can set on a treemap control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

Buzz when you tap

Plays this touch feedback when a cell is tapped; leave it empty for a light tap.

  • noneno feedback
  • lighta gentle tap
  • mediuma medium tap
  • heavya strong tap
  • softa cushioned tap
  • rigida sharp tap
  • selectiona tiny tick like scrolling a picker
  • successa confirming pattern
  • warninga cautioning pattern
  • errora sharp error pattern
Titlelabeltext—

The title above the blocks

Shows this text as the header, which becomes a back button while you are zoomed into a group.

treemapConfigtreemapConfigobject—

Extra block settings

Holds the optional look and behavior settings for the blocks.

Colortintcolor#667eea

The main block color

Colors the first block and seeds the colors of the rest.

formatValueformatValuetext—

How numbers are written

Formats the values shown on blocks, for example with a unit after the number.

Cell roundnesstreemapConfig.cellCornerRadiusnumber0–30 ptstep 15

How round the blocks are

Rounds each block's corners from square to 30 points.

Cell spacingtreemapConfig.cellGapnumber0–40 ptstep 12

The space between blocks

Leaves this many points of gap between neighboring blocks.

Cell colorstreemapConfig.colorsstring[]—

Colors for the blocks

Gives blocks colors from this list in turn; a color set on an item wins.

drillDowntreemapConfig.drillDownon / offtrue (on)

Tap a group to open it

When on, tapping a block with items inside zooms into it; when off, every tap acts as a pick.

itemActiontreemapConfig.itemActionobject—

What happens when you pick a block

Runs this action when you tap a block with nothing inside, passing its label, value and path.

scrubtreemapConfig.scrubon / offfalse (off)

Slide a finger across the blocks

When on, dragging highlights the block under your finger with a live readout, and only a tap drills in or acts.

LabelstreemapConfig.showLabelson / offtrue (on)

Names on the blocks

Draws each block's name inside it where there is room.

Value labelstreemapConfig.showValueson / offfalse (off)

Numbers on the blocks

Draws each block's value under its name on blocks tall enough to fit.

Theme fields

Restyle one control by setting these in its theme object; a layout's theme sets them for every control.

Theme fields
FieldTypeDefaultWhat it does
secondaryColortheme.secondaryColorcolor#FFFFFF99

Space inside the edge

Colors the block names and header text.

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 tap a blockitemtapjson

the tapped block, as JSON with its label, size and path

A block with items inside opens instead when drill down is on, and sends nothing

Example: {"label": "Item 1", "value": 3, "path": [0]}

Receives

Receives
TakesFromTypeWhat it does
itemsshowhub, mqtt, http, store, defaultjson

items: a label and a size each, which can hold more items inside

the blocks resize to their new share of the whole; a new label adds a block

Example: {"items": [{"label": "Item 1", "value": 3}, {"label": "Item 2", "value": 2}]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"items": [{"label": "Item 1", "value": 4}, {"label": "Item 2", "value": 3}, {"label": "Item 3", "value": 2}, {"label": "Item 4", "value": 1}]} then {"items": [{"label": "Item 1", "value": 2}, {"label": "Item 2", "value": 3}, {"label": "Item 3", "value": 4}, {"label": "Item 4", "value": 1}]}

Examples

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

Storage map with drill-down

JSON 10 lines
{
  "type": "treemap",
  "id": "storage",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Storage",
  "formatValue": "suffix: GB",
  "treemapConfig": { "showValues": true },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "disk_usage" }, "valuePath": "tree" }]
}

Open in CAR-TER

Blocks: Storage map with drill-down
Rendered by the app

Flat category picker (no drill)

JSON 12 lines
{
  "type": "treemap",
  "id": "budget",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Budget",
  "treemapConfig": {
    "drillDown": false,
    "itemAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "pick_category", "item": "{{value}}" } }
  },
  "defaultValue": "[{\"label\":\"Rent\",\"value\":1800},{\"label\":\"Food\",\"value\":600},{\"label\":\"Fun\",\"value\":250},{\"label\":\"Save\",\"value\":900}]"
}

Open in CAR-TER

Blocks: Flat category picker (no drill)
Rendered by the app

Colored blocks with a scrub readout

Sets your own block colors and lets a drag glide across cells. Intended effect: sliding a finger highlights each block with its value, without zooming in.

JSON 9 lines
{
  "type": "treemap",
  "id": "portfolio",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Portfolio",
  "treemapConfig": { "scrub": true, "showValues": true, "cellGap": 4, "colors": ["#667eea", "#f6ad55", "#48bb78"] },
  "defaultValue": "[{\"label\":\"Stocks\",\"value\":60},{\"label\":\"Bonds\",\"value\":25},{\"label\":\"Cash\",\"value\":15}]"
}

Open in CAR-TER

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Storage map with drill-down” on your phone.

    carterkit demo treemap --example 'Storage map with drill-down'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Wide: [3, 4]. In a flow grid it auto-sizes to a ~3:2 landscape cell.

TreemapConfig

Field Type Default Description
showLabels bool true Item labels inside cells that have room
showValues bool false Value under the label (taller cells only)
drillDown bool true Tap a parent to zoom into its children
cellGap number 2 Gap between cells
cellCornerRadius number 5 Cell corner rounding
colors string[] built-in palette Item color cycle (per-item color wins)
itemAction ActionDefinition — Fired on leaf tap; {{value}} = {"label", "value", "path"}
scrub bool false Drag highlights the cell under the finger with a live readout (no drilling/actions until a tap)

Sync Payload Structure

A tree of weighted items — natural JSON or an encoded string. A bare array is shorthand for {"items": …}. A parent's value defaults to the sum of its children:

{
  "items": [
    { "label": "Media", "color": "#667eea", "children": [
      { "label": "Video", "value": 41.5 },
      { "label": "Photos", "value": 12.2 }
    ]},
    { "label": "Apps", "value": 23.0 },
    { "label": "System", "value": 14.8 }
  ]
}

Item Fields

Field Type Required Description
label string yes Cell label
value number no* Weight (*optional when children supply it)
color string no Cell color (hex)
children item[] no Nested items (drill-down target)

Behavior

  • Layout is the squarified algorithm (Bruls et al.) — rectangles stay as close to square as the weights allow
  • Parents show a › hint; drilling cross-fades levels; the back chip walks one level up
  • A fresh dataset push resets the drill path (the old path may not exist anymore)
  • Labels only render where they fit — small slivers stay clean
  • scrub: true lets a drag glide the highlight across cells — drilling and actions stay on deliberate taps

Notes

  • The control's value is the dataset JSON — selection/drill state never overwrites it
  • Zero/negative values collapse to invisible slivers by design
  • For part-of-whole with few slices, Start angle reads faster; treemap earns its space at ~6+ items or with hierarchy

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