UI & Layout¶

The ui block in app/settings.ts tunes the shell — panel sides and widths, the top bar, the layer list, the info modal, the loading overlay, mobile sizing, and more. Every sub-block is optional; omit any of them for the defaults.

ui: {
  layout: { /* … */ },
  topBar: { /* … */ },
  layerList: { /* … */ },
  info: { /* … */ },
  loader: { /* … */ },
  widgetHeader: { /* … */ },
  layerDefaults: { /* … */ },
  mobile: { /* … */ },
  buttonCursor: 'pointer',
  popups: { /* documented separately — see the Popups page */ },
},

Popups has its own page. Everything else is below.

Layout — ui.layout¶

Controls which side of the desktop shell each region sits on, panel widths, and whether the branding/info cluster shows. Desktop only — the mobile shell ignores the side fields.

Top bar — ui.topBar¶

Top-bar shadow¶

A subtle shadow under the top bar, scoped to the map window only — it never falls over the side panels, so it stays put when a panel slides out.

topBar: { height: 56, shadow: { enabled: true, strength: 0.4 } },

Layer list — ui.layerList¶

Defaults for the Layer List widget.

Per-group collapse can be overridden via the top-level layerGroups block:

layerGroups: {
  'ESRI Services': { collapsed: true },
},

Info modal — ui.info¶

The "About this app" modal renders app/info.md. By default it's click-only (the top-bar ⓘ button); these knobs let it greet users on load.

With autoOpen on, a plain close (X / Escape / backdrop) is temporary — it reopens next load. Only ticking "don't show again" (which requires allowDismiss) suppresses future auto-opens.

Loading overlay — ui.loader¶

A boot-time overlay shown while initial layer data is fetching. It dims the app and blocks clicks so a widget can't be opened mid-load. The spinner color tracks the primary token.

It only waits for layers that are visible at startup — hidden layers don't load until you turn them on, so they never hold the overlay open. With no visible layers at all (an empty app, or every layer set to visible: false), it clears as soon as the basemap has loaded.

Widget header — ui.widgetHeader¶

The shared title bar atop widget panels (label + close X + optional divider).

These are global defaults; individual placements can override them per widget (see Building a Custom Widget). The title's color is a theme setting — widgetTitleColor in app/theme.ts, see Theme.

Global layer defaults — ui.layerDefaults¶

Set a default once for all layers instead of repeating it on each. Per-layer values always win. Currently this covers label styling (only affecting layers that opted into labels).

layerDefaults: {
  label: { font: 'Noto Sans Bold', fontSize: 12, color: '#333333', haloColor: '#ffffff', haloWidth: 1 },
},

The fields mirror a layer's label config (minus the per-layer field/expression/minZoom, which are content, not style). Omit for the kit defaults: Noto Sans Regular, 12px, #333, white halo.

Mobile — ui.mobile¶

Sizing for the mobile bottom sheet, as a fraction of the viewport height (vh).

Button cursor — ui.buttonCursor¶

Right-click context menu — contextMenu¶

A top-level block (not under ui). The desktop-only right-click menu. Each built-in is opt-in by presence; custom items append last. Omit the whole block to restore the browser's native right-click menu.

contextMenu: {
  centerHere: true,
  googleMaps: true,
  googleStreetView: true,
  // osm: true, appleMaps: true, copernicus: true,
  custom: [
    { label: 'Open in Bing Maps', url: 'https://www.bing.com/maps?cp={lat}~{lng}&lvl={zoom}' },
  ],
},