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). It will start out expanded, but once a user pans on the map it will become compact and collapsed by default — the user expands it with the "ⓘ" button. This is a shell decision, not configured here. If you need this adjusted, you can manually change the shell code.

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. For an example of this, see how the search widget is implemented in the default repository.