Widget Placement
This page explains how Cartography KPI widgets are placed, moved, and resized on a Horizon board.
1. Switch to Edit Mode
In the board canvas top bar, click the Edit Mode toggle. While edit mode is active:
- Grid lines become visible
- Drag handles and resize handles become active on existing widgets
- The Add Chart button enables adding new widgets
- Delete icons appear on widget cards
2. Add Chart Dialog
Click the Add Chart button on the top bar. The dialog that opens lists the Cartography widget library.
| Dialog Features |
|---|
| Search — filter by widget name |
| Chart Type Filter — Cartesian / Circular / Gauge / Text / DataGrid / Other |
| Tag Filter — tags assigned in Cartography |
| Folder Tree — Cartography folder path |
| Card Preview — small preview |
Click to select your widget, then add it to the board with Add.
Quick Add
To show the same query with different widget types, use Duplicate in Cartography to copy and assign a different chart type → Cartography Duplicate.
3. Widget Placement
The added widget appears at a default position on the board (usually empty area top-left). Hold the widget's top edge to drag.
| Action | Behavior |
|---|---|
| Drag | Move widget to a new cell; snap-back if overlapping |
| Resize corner handle | Expand/shrink (min 7×5 cells) |
| Delete (X) icon | Remove widget from board (does not delete it from Cartography) |
Snap to Grid
The dragged widget snaps to the nearest cell coordinate (snap-to-grid). On the 180-column V1 grid, the cell size is computed dynamically from canvas width.
4. Widget Limits
| Limit | Value |
|---|---|
| Maximum widgets per board | 20 |
| Minimum width | 7 cells |
| Minimum height | 5 cells |
| Maximum width | 180 (entire row) |
| Overlap behavior | Snap-back; no overlapping placement |
When Maximum Widgets Reached
When you reach 20 widgets, Add Chart warns: "Maximum 20 charts per board". To add a new widget, remove an existing one first.
5. Widget Interactions (Edit Mode Off)
When you exit edit mode, widgets become interactive:
| Interaction | Behavior |
|---|---|
| Cartesian / Circular | Tooltip, zoom, pan, trackball (per Cartography settings) |
| Gauge | Display only |
| Text | Display only |
| DataGrid | Sort, filter, row selection |
| Two-Column List | Display only |
Visible vs Hidden in Edit
While edit mode is active, widget interactive features are disabled (drag/resize takes priority). Exit edit mode to test the widget in its final state.
6. Widget Order
In the layout JSON, widget order determines z-order: a widget added later is rendered on top. Since the V1 grid does not allow overlap, z-order rarely matters in practice.
7. Save After Edits
When you exit edit mode the layout is auto-saved. Make sure to click Done or a similar exit button before closing the browser.
8. Common Errors
| Symptom | Possible Cause | Solution |
|---|---|---|
| Widget will not add | 20-widget limit reached | Remove an existing widget |
| Widget does not load data | Compass query has an error | Test the query in Compass |
| Widget shows "Widget not found" | Deleted in Cartography | Replace with a new widget |
| Drag/resize does not work | Edit mode is off | Turn on the Edit Mode toggle |