---
title: "MaplibreSource"
description: "A declarative data source supporting geojson / vector / raster / image / video, with incremental updates by type and the ability to be shared across multiple layers."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/core/source"
---
# MaplibreSource

> A declarative data source supporting geojson / vector / raster / image / video, with incremental updates by type and the ability to be shared across multiple layers.

## Introduction

`MaplibreSource` declaratively manages a maplibre-gl data source: it calls `addSource` when the map is ready, applies incremental updates when `source` changes (e.g. `setData` for geojson, `setTiles` for vector) instead of recreating the whole source, and safely removes it on unmount. Child layers reference the source by its `source="<sourceId>"` string.

> [!TIP]
> See: /docs/core/layer
> 
> A single source can be consumed by multiple layers simultaneously — this is the key advantage of an explicit 
> 
> MaplibreSource
> 
>  over an inline source inside 
> 
> MaplibreLayer
> 
> .

## Usage

One geojson source driving both a halo and a filled circle layer at the same time:

```vue [SourceGeojsonExample.vue]
<script setup lang="ts">
import type { FeatureCollection } from 'geojson'

// 同一数据源同时供「实心圆」与「光晕」两个图层消费
const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: {}, geometry: { type: 'Point', coordinates: [116.397, 39.908] } },
    { type: 'Feature', properties: {}, geometry: { type: 'Point', coordinates: [116.45, 39.93] } },
    { type: 'Feature', properties: {}, geometry: { type: 'Point', coordinates: [116.35, 39.88] } }
  ]
}
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ style: 'https://tiles.openfreemap.org/styles/positron', center: [116.4, 39.9], zoom: 11 }">
      <MaplibreSource source-id="cities" :source="{ type: 'geojson', data }">
        <MaplibreLayer
          layer-id="cities-halo"
          type="circle"
          source="cities"
          :paint="{ 'circle-radius': 18, 'circle-color': '#3b82f6', 'circle-opacity': 0.2 }"
        />
        <MaplibreLayer
          layer-id="cities-core"
          type="circle"
          source="cities"
          :paint="{ 'circle-radius': 7, 'circle-color': '#3b82f6' }"
        />
      </MaplibreSource>
    </MaplibreMap>
  </div>
</template>
```

## Examples

### Reactive Updates

`source` is reactive: switching datasets only triggers `setData` — no layers are rebuilt:

```vue [SourceUpdateExample.vue]
<script setup lang="ts">
import type { FeatureCollection } from 'geojson'

function randomPoints(count: number, seed: number): FeatureCollection {
  return {
    type: 'FeatureCollection',
    features: Array.from({ length: count }, (_, i) => ({
      type: 'Feature',
      properties: {},
      geometry: {
        type: 'Point',
        coordinates: [116.2 + ((i * seed) % 40) / 100, 39.8 + ((i * seed * 7) % 25) / 100]
      }
    }))
  }
}

const datasets = [randomPoints(12, 13), randomPoints(40, 31)]
const index = ref(0)

// source 为响应式：切换数据集仅触发 setData 增量更新，不重建源
const source = computed(() => ({ type: 'geojson' as const, data: datasets[index.value]! }))
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ style: 'https://tiles.openfreemap.org/styles/positron', center: [116.4, 39.9], zoom: 10 }">
      <div class="absolute left-3 top-3 z-10">
        <UButton size="xs" color="neutral" variant="solid" @click="index = index === 0 ? 1 : 0">
          Toggle dataset
        </UButton>
      </div>
      <MaplibreSource source-id="pts" :source="source">
        <MaplibreLayer
          layer-id="pts"
          type="circle"
          source="pts"
          :paint="{ 'circle-radius': 6, 'circle-color': '#3b82f6', 'circle-opacity': 0.8 }"
        />
      </MaplibreSource>
    </MaplibreMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MaplibreSource component
 */
interface MaplibreSourceProps {
  /**
   * 数据源 id，供图层经 source 字段按字符串引用；变更需配合 `:key` 重建
   */
  sourceId: string;
  /**
   * 数据源定义，变化时按类型增量更新（setData / setTiles 等）
   */
  source: SourceSpecification;
}
```

### Slots

```ts
/**
 * Slots for the MaplibreSource component
 */
interface MaplibreSourceSlots {
  default(): any;
}
```

## Changelog

See commit history for [src/runtime/components/MaplibreSource.vue](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/components/MaplibreSource.vue).


## Sitemap

See the full [sitemap](https://maplibre.mhaibaraai.cn/sitemap.md) for all pages.