Skip to content

Map Controls

The mapControls block adds MapLibre's native controls to the map's corners — zoom buttons, a "locate me" button, fullscreen, a scale bar, and a globe toggle. These are first-party MapLibre controls, distinct from the kit's floating widgets (though both can share the map corners).

Each control is opt-in by presence: include its key to add it, omit the key to leave it out. Omit the whole mapControls block for no native controls.

mapControls: {
  navigation: { position: 'top-left' },
  geolocate:  { position: 'top-right', trackUserLocation: true },
  globe:      { position: 'top-right' },
},

Controls

Key Control Default position
navigation Zoom +/− buttons and a compass top-left
geolocate "Locate me" button (browser geolocation) top-left
fullscreen Toggles browser fullscreen on the map top-right
scale A distance scale bar bottom-left
globe Toggles globe ↔ mercator projection top-right

All five take an optional position of 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'. MapLibre auto-stacks multiple controls in the same corner in insertion order.

Per-control options

Field Type Default Description
position ControlPosition top-left Corner
showZoom boolean true Show the +/− zoom buttons
showCompass boolean true Show the compass
visualizePitch boolean forced on The kit forces this on so the compass tilts with pitch and a compass click flattens 3D → 2D in one animation

geolocate

Field Type Default Description
position ControlPosition top-left Corner
trackUserLocation boolean false Keep following the user as they move
showUserLocation boolean true Show the location dot
showUserHeading boolean false Show a heading cone
showAccuracyCircle boolean true Show the accuracy halo

scale

Field Type Default Description
position ControlPosition bottom-left Corner
unit 'metric' \| 'imperial' \| 'nautical' 'metric' Distance unit
maxWidth number — Max bar width in pixels

fullscreen and globe

Both take only position.

Attribution

MapLibre's attribution control is always present (it's required for most basemaps), rendered compact and collapsed by default — the user expands it with the "ⓘ" button. This is a shell decision, not configured here.

Native controls vs. floating widgets

The native controls above and the kit's floating widgets share the same four map corners. When you place a floating widget in a corner that also has native controls, MapLibre stacks the native ones first; use the widget's order field (a negative value) to lift it above them. See Building a Custom Widget.