Working with widgets

Widgets are the building blocks placed on a view. Each one is a React component registered in a central widget registry, configured through a side drawer, and able to wire to other widgets via cross-widget actions.

This page covers using widgets. To add a new widget type, see Creating a widget. For the registry API, see Widget registry.

The widget catalog

The registry currently exposes these widgets (src/widgets/registry.tsx). Each links to its detailed guide:

Type	Name	What it shows
arcgis-map	ArcGIS Map	An interactive WebMap surface.
arcgis-legend	Legend	Layer symbology bound to a Map widget.
arcgis-link-chart	Link Chart	A knowledge graph from a Cypher query.
table-card	Table	A sortable data table with row actions.
list	List	Items from a Feature Service layer.
indicator	Indicator	A headline statistic or feature value.
details	Details	A popup/details panel fed by a Map widget.
world-clock	World Clock	A live digital clock.
ai-chat	AI Chat	A conversational Q&A panel.
ai-agents	AI Agents	An agent roster with live status.
gantt-chart	Gantt Chart	A schedule timeline.

For a per-widget breakdown of configuration, data sources, and actions, see the Widget catalog.

Adding and arranging

The canvas is a tiling layout: widgets never overlap and always fill the view edge to edge, so arranging is about splitting and resizing tiles rather than freely dragging boxes around.

1. Open the widget picker and choose a type. The All tab lists every widget; the remaining tabs group widgets by category (Maps & GIS, Data & Charts, AI & Imagery, Media & Tools), each shown with an icon. A new instance is added with the registry's defaultSize (and defaultConfig, if any). The first widget on an empty view fills the whole canvas.
2. Place each subsequent widget by hovering an existing tile. Five zone buttons appear over it: the four edges (top / right / bottom / left) split that tile 50/50 and drop the new widget on that side; the center button adds the widget as a tab in that tile (see Widget groups). A live ghost previews where it will land. Press Escape during placement to cancel it and reopen the widget picker.
3. Move an existing widget by pressing its header and dragging onto another tile, then releasing over one of the same zone buttons — one continuous gesture, no second click.
4. Resize by dragging the divider between two tiles. Dividers move in fine steps and tiles can shrink all the way down to a single grid cell — there is no per-widget minimum size.
5. Layout changes auto-save with the rest of the workspace.

In edit mode the canvas shows a subtle dot grid behind the widgets and a uniform gap between tiles (and around the canvas edge) so the layout is easy to read while arranging. The dots are hidden in view mode.

In view mode the canvas is read-only — no placing, moving, resizing, or configuration.

Configuring a widget

Clicking the gear icon on a widget toggles the config drawer (WidgetConfigDrawer). Clicking the same widget's gear again closes the drawer. Clicking the widget body does not open the drawer, so widgets can be arranged on the canvas without it getting in the way. It has up to three sections:

• Data — the widget's data source. Hidden for dataless widgets (such as World Clock and AI Chat); those open on Appearance instead.
• Appearance — presentation options.
• Actions — cross-widget wiring. Hidden for widgets flagged hideActions.

The drawer renders a type-specific panel registered in src/widgets/config.tsx. Widgets without a custom panel still get the title field and any applicable default sections.

The drawer docks to the right of the canvas by default. The panel icon in its header moves it to the left (and back), which is handy when a widget is docked to the right edge. The chosen side is remembered across sessions.

Sample data vs. configured data

Data-driven widgets (Map, Table, Indicator, Legend, List) render a "configure me" placeholder until their data source is set, rather than showing mock content. When a widget's config is set on the view, it is merged over the widget's bundled sample defaults and passed through as the widget's data.

Cross-widget actions

Widgets can drive each other. For example:

• A Map emits a map:extent-change action when the user finishes panning/zooming, which a Table or List can consume as a filter.
• A Map emits map:layer-click when a feature is clicked, which a Details widget can consume to show that feature.

Wiring is stored on the source widget (WidgetInstance.actions) and configured in the drawer's Actions section. The full routing model is documented in Cross-widget actions.

Sharing a live map view

The Map and Legend widgets share a live ArcGIS MapView through the MapViewRegistry (src/widgets/internal/MapViewRegistry.tsx), so a Legend can bind to the layers of a sibling Map on the same view.