Svelte Maplibre

API / Map

MapLibre

Create a MapLibre map. Put all other components of this library inside this component's children.

This component makes the map context. Sources, layers, markers, popups and controls inside it use this context to find the map. The children render only after the map is created, and they receive map, loaded, loadedImages, and allImagesLoaded.

center, zoom, pitch, bearing, and bounds are bindable. The component updates them when the map stops moving, and it moves the map when you change them. map, mapContainer, and loaded are also bindable. Most other options, such as minZoom, maxZoom, interactive, and transformRequest, are applied only when the map is created.

When style changes, the component keeps the sources and layers that you added and adds them again after the new style loads. It also loads images again. Set hash to keep the viewport in the URL hash. Set standardControls to add the navigation, geolocate, fullscreen, and scale controls.

import { MapLibre } from 'svelte-maplibre';

Examples

Props

  • map bindable maplibregl.Map
  • mapContainer bindable HTMLDivElement

    The div element that the Map is placed into. You can bind to this prop to access the element for yourself. Setting it externally will have no effect.

  • class string
  • style required string | maplibregl.StyleSpecification

    The style to use for the map.

  • diffStyleUpdates boolean

    Default: false

    Tell MapLibre to update the map in place when changing the style, diffing the old style against the new one to make minimal changes. If you enable this, be aware of https://github.com/maplibre/maplibre-gl-js/issues/2651, which may prevent some style changes from becoming visible when diffing is enabled.

  • aroundCenter boolean
  • center bindable LngLatLike
  • zoom bindable number
  • pitch bindable number

    Default: 0

  • bearing bindable number

    Default: 0

  • bearingSnap number

    Default: 7

  • bounds bindable LngLatBoundsLike
  • fitBoundsOptions FitBoundsOptions

    Default: {}

  • projection maplibregl.ProjectionSpecification
  • zoomLevelsToOverscale number | null

    Default: 4

    How many zoom levels past a source's maxzoom to overscale its tiles. Below that, tiles are split instead, which improves labeling at high zoom. Pass null to overscale at every zoom level, restoring the behavior from before MapLibre 6. Only applied when the map is created.

  • hash boolean

    Default: false

    Set to true to track the map viewport in the URL hash. If the URL hash is set, that overrides initial viewport settings.

  • updateHash (url: URL) => void

    Default: (url) => { window.history.replaceState(window.history.state, '', url); }

    Update the URL when the hash changes, if hash is true. The default behavior uses window.history.replaceState. For SvelteKit, you should import { replaceState } from '$app/navigation'; and pass something like updateHash={(u) => replaceState(u, $page.state)} when instantiating the map.

  • loaded bindable boolean

    Default: false

  • minZoom number

    Default: 0

  • maxZoom number

    Default: 22

  • minPitch number

    Default: 0

  • maxPitch number

    Default: 60

  • renderWorldCopies boolean
  • dragPan boolean
  • dragRotate boolean
  • pitchWithRotate boolean
  • antialias boolean
  • zoomOnDoubleClick boolean

    Default: true

  • locale any

    Override MapLibre's default locale table

  • interactive boolean

    Default: true

  • attributionControl false | maplibregl.AttributionControlOptions

    Set false to hide the default attribution control, so you can add your own.

  • cooperativeGestures boolean

    Default: false

    Set true to require hitting ⌘/Ctrl while scrolling to zoom. Or use two fingers on phones.

  • preserveDrawingBuffer boolean

    Default: false

    Set to true if you want to export the map as an image

  • maxBounds LngLatBoundsLike
  • images CustomImageSpec[]

    Default: []

    Custom images to load into the map.

  • standardControls boolean | maplibregl.ControlPosition

    Default: false

    Set to true or a position to add all the standard controls.

  • filterLayers ((layer: maplibregl.LayerSpecification) => boolean)

    Filter the map's builtin layers, hiding any for which this function returns false.

  • transformRequest maplibregl.RequestTransformFunction

    Function that modifies requests, such as by adding an API key. *

  • children Snippet<[ { map: maplibregl.Map; loaded: boolean; loadedImages: Set<string>; allImagesLoaded: boolean; } ]>
  • onload (map: maplibregl.Map) => void
  • onerror (error: Partial<ErrorEvent>) => void
  • onclick (e: maplibregl.MapMouseEvent) => void
  • ondblclick (e: maplibregl.MapMouseEvent) => void
  • onmousemove (e: maplibregl.MapMouseEvent) => void
  • oncontextmenu (e: maplibregl.MapMouseEvent) => void
  • onmovestart (e: MapMoveEvent) => void
  • onmoveend (e: MapMoveEvent) => void
  • onzoomstart (e: maplibregl.MapMovementEvent) => void
  • onzoom (e: maplibregl.MapMovementEvent) => void
  • onzoomend (e: maplibregl.MapMovementEvent) => void
  • onpitch (e: maplibregl.MapMovementEvent) => void
  • onrotate (e: maplibregl.MapMovementEvent) => void
  • onwheel (e: maplibregl.MapWheelEvent) => void
  • ondata (e: maplibregl.MapSourceDataEvent | maplibregl.MapStyleDataEvent) => void
  • onstyleload (e: StyleLoadEvent) => void
  • onstyledata (e: maplibregl.MapStyleDataEvent) => void
  • onidle (e: maplibregl.MapLibreEvent) => void

Source: src/lib/MapLibre.svelte