Svelte MapLibre GL

Svelte MapLibre GL provides a declarative and reactive interface for MapLibre GL JS using Svelte 5.

Key characteristics:

• Declarative & Reactive: Powered by Svelte 5 for idiomatic state management.
• Flexible API: Designed to be minimally opinionated, making it accessible for beginners while remaining powerful for advanced users.
• Imperative Support: You can still use traditional imperative MapLibre GL JS methods alongside the Svelte components to preserve full control.

Create a new SvelteKit project using the official Svelte CLI. It is recommended to enable the Tailwind CSS add-on during setup, as the library's examples use it for styling.

npx sv create myapp
# Make sure to enable the Tailwind CSS add-on,
# as our examples use it for styling.

cd myapp
npm install

Install the svelte-maplibre-gl package using npm to start building interactive web maps with MapLibre GL JS and Svelte 5.

npm install --save-dev svelte-maplibre-gl

Use MapContext to manage layers. These methods are safe to call even if the map style is still loading; the operations will be queued and executed once the style is ready.

• addLayer(addLayerObject, beforeId?): Adds a layer. addLayerObject follows the maplibregl.AddLayerObject specification. beforeId is an optional ID of an existing layer to place this new layer before.
• removeLayer(id): Removes the layer with the specified id.

const mapCtx = getMapContext();

// Adding a layer
mapCtx.addLayer({
  id: 'my-layer',
  type: 'circle',
  source: 'my-source',
  paint: { 'circle-radius': 10 }
});

// Removing a layer
mapCtx.removeLayer('my-layer');

To use the map context in a Svelte application, you must first initialize it in a parent component (usually where the map is instantiated) and then retrieve it in child components.

• prepareMapContext(): Creates a new MapContext and sets it into the Svelte context. This should be called in a top-level map component.
• getMapContext(): Retrieves the existing MapContext from the Svelte context. Throws an error if no context is found.

// In a parent component
import { prepareMapContext } from 'svelte-maplibre-gl';
prepareMapContext();

// In a child component
import { getMapContext } from 'svelte-maplibre-gl';
const mapCtx = getMapContext();

To display data, you must first define a source using components like VectorTileSource, GeoJSONSource, or RasterTileSource, and then add a layer (such as FillLayer, LineLayer, or SymbolLayer) that references that source. Layers are typically placed as children of the Map component.

<script>
  import { Map, GeoJSONSource, FillLayer } from 'svelte-maplibre-gl';
  import myData from './data.json';
</script>

<Map>
  <GeoJSONSource data={myData} id="my-data" />
  <FillLayer source="my-data" />
</Map>

Use MapContext to manage data sources. Like layers, these operations are queued until the map style is loaded.

• addSource(id, source): Adds a source with the given id and source specification (e.g., GeoJSONSourceSpecification, RasterSourceSpecification).
• removeSource(id): Removes the source with the specified id.

const mapCtx = getMapContext();

// Adding a source
mapCtx.addSource('my-source', {
  type: 'geojson',
  data: { type: 'FeatureCollection', features: [] }
});

// Removing a source
mapCtx.removeSource('my-source');

The MapLayerEventProps type is a utility that maps standard MapLibre GL layer event types to Svelte-friendly on<Event> prop names. For every event type available in maplibregl.MapLayerEventType, this type provides an optional handler function prefixed with on.

For example, if MapLibre provides a click event, you can use onclick as a prop in your Svelte component. The event object passed to the handler will be the standard MapLibre event type for that specific event.

// Example of how the mapping works conceptually:
// If maplibregl.MapLayerEventType has: click: MapLayerEventType['click']
// MapLayerEventProps will have: onclick?: (ev: maplibregl.MapLayerEventType['click']) => void;

Use the Marker component to place points on the map and the Popup component to show information when a marker or feature is interacted with. Markers are typically children of the Map component.

<script>
  import { Map, Marker, Popup } from 'svelte-maplibre-gl';
</script>

<Map>
  <Marker lng={10} lat={10}>
    <Popup>
      <p>Hello World!</p>
    </Popup>
  </Marker>
</Map>