Building a Custom Widget¶

The full reference for authoring widgets — the manifest, surfaces, placement options, icons, and the shared chrome conventions. If you haven't yet, walk through Your First Widget first; this page assumes that loop.

Anatomy of a widget¶

A widget is a folder under app/widgets/. The shell only ever looks at one file — widget.config.ts, which must export const manifest. Everything else in the folder is yours to organize.

app/widgets/my-widget/
├── widget.config.ts   ← the manifest (the only file the shell reads)
├── Component.tsx       ← your React component
├── icon.svg            ← the launcher icon
└── …                   ← anything else you need

A folder whose name starts with _ is skipped by auto-discovery — that's how _template stays out of your app.

The manifest¶

export interface WidgetManifest {
  id: string
  label: string
  description?: string
  icon: string
  icons?: Partial<Record<IconSurface, string>>
  surfaces: WidgetSurface[]
  defaults?: WidgetDefaults
  component: ComponentType
}

defaults¶

defaults: { panelWidth: 320, hasUI: true, chromeless: false, stayOnMobile: false }

Surfaces¶

A widget declares the surfaces it supports; you place it by adding its id to the matching array in settings.ts. Placing a widget on a surface it doesn't declare throws at boot.

Placement options¶

Each placement entry is a WidgetPlacement:

{ widgetName: 'my-widget', panelWidth: 360, header: { showTitle: false } }

Floating placement¶

Floating widgets go in a slot keyed by corner:

floatingWidgets: [
  {
    slot: 'top-left',          // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
    direction: 'vertical',     // stack direction (optional)
    spacing: 8,                // gap in px (optional)
    widgets: [{ widgetName: 'search', order: -1 }],
  },
],

MapLibre's native controls sit at order: 0, and it stacks corner items by source order with native controls first. So a negative order (e.g. -1) lifts your widget above the native controls in the same corner; a positive value pushes it below.

Connecting to the map¶

Use the hooks from @/core/hooks:

import { useMap, useMapReady } from '@/core/hooks'

const map = useMap()       // the MapLibre map (or null before it exists)
const ready = useMapReady() // true once the style has loaded

Always gate map work on ready. For shared state across widgets, read the Zustand store via useStore from @/core/store (see Internals).

Icons¶

The launcher icon is an imported SVG. You only need one file, and its color doesn't matter. The shell draws every launcher icon as a shape and fills it with the right theme color for wherever it appears:

So the same file works on every surface and in every preset. Conventions (from the template):

• Use a 24×24 viewBox and stroke-width="2" — that matches the weight of MapLibre's zoom/compass buttons beside a floating icon. Solid fills work too.
• Keep stroke-linecap / stroke-linejoin round like the built-ins.
• Draw it in any single color. To shade parts of an icon, use fill-opacity rather than different colors — different opaque colors all come out as the same solid shape.

icons still exists for the rare case where a surface needs a genuinely different shape — e.g. a simpler glyph for the small mobile-carousel button. Never use it for color:

icon,                                  // used everywhere by default
icons: {
  mobile: iconMobile,                  // a simpler shape for the mobile carousel
},

Color tokens¶

Use the semantic theme utilities for your widget's chrome so it re-skins with the rest of the app from app/theme.ts — dark presets included. Avoid raw colors like bg-white, text-slate-900, or border-gray-200: they'll stay light when the user picks a dark preset.

The full token list, with defaults, is on the Theme page.

These work on every surface, including floating pop-outs — a global rule neutralizes MapLibre's button-hover style there, so you never need surface-specific CSS.

Styling with a plain .css file (like the built-in Draw and Measure widgets)? Use var(--color-<token>) — e.g. background: var(--color-panelBg) — never a hex value. For the rare thing a token can't express (such as an icon baked into a data URI), target the dark presets with [data-theme='dark'] .my-widget …. app/widgets/draw/draw.css and measure/measure.css are worked examples.

Colors painted on the map are the exception — MapLibre layer styles can't read CSS variables.

For a standard list-row hover (tinted background + left accent), add the kit-row-hover class to the row.

For a small scrolling box, add kit-scrollbar to show a thin scrollbar at all times — macOS (Safari especially) otherwise hides it until you scroll, so the box doesn't look scrollable.

Shared chrome¶

Don't hand-roll these — import the shared pieces so every widget looks consistent:

• Action glyphs — import { TrashIcon, EditNameIcon, DownloadIcon, CloseIcon } from '@/core/icons'. TrashIcon = delete data; CloseIcon (the X) = dismiss. They use currentColor, so color them via the button's text color.
• Toggles — import { ToggleSwitch } from '@/shell/ToggleSwitch' for on/off settings: <ToggleSwitch checked={on} onChange={setOn} ariaLabel="Show totals" />. It has no text of its own, so pair it with a label (and always pass ariaLabel). Colored by the slider token when on.
• Confirmations — import { ConfirmDialog } from '@/shell/ConfirmDialog' for "are you sure?" prompts. Render it as a child of your widget's root (give the root relative); it dims and blocks the widget until the user chooses. variant="danger" = red confirm; variant="default" = primary.

Widget-specific settings¶

If your widget needs author config, add a block to Settings (in app/src/core/types.ts) and read it via import { settings } from '@user/settings'. The built-in search / measure / draw / bookmarks widgets follow this pattern — see their pages under Widgets.