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.

Widget header — ui.widgetHeader¶

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

This is a global default; individual placements can override it per widget (see Building a Custom Widget).

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}' },
  ],
},