---
title: "MaplibreBasemapControl"
description: "Basemap switcher bound to the same value as the map options.style, switching Tianditu and vector styles the same way."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/controls/basemap-control"
---
# MaplibreBasemapControl

> Basemap switcher bound to the same value as the map options.style, switching Tianditu and vector styles the same way.

## Introduction

`MaplibreBasemapControl` is a controlled component: it only handles selection, emitting the selected item's `style` through `v-model` without calling `setStyle`. Bind the same value to the `options.style` of `MaplibreMap`, and the map switches the style and rebuilds overlay layers automatically. The style lives in one place, so the control and the map never disagree.

Generate a full style for Tianditu basemaps with [`tiandituStyle()`](https://maplibre.mhaibaraai.cn/docs/extensions/tianditu), and switch it together with vector styles such as OpenFreeMap in the same `items` list.

> [!TIP]
> 
> After switching basemaps, the visibility and opacity of each 
> 
> MaplibreLayerGroup
> 
> , including basemap layers adopted through 
> 
> styleLayers
> 
> , are restored on the new style automatically.

## Usage

```vue [BasemapControlExample.vue]
<script setup lang="ts">
import type { BasemapItem } from '#maplibre/types'
import { tiandituStyle } from '@movk/maplibre/utils/tianditu'

const items: BasemapItem[] = [
  { label: 'OpenFreeMap Liberty', style: 'https://tiles.openfreemap.org/styles/liberty' },
  { label: 'OpenFreeMap Dark', style: 'https://tiles.openfreemap.org/styles/dark' },
  { label: '天地图 影像', style: tiandituStyle('img', { annotation: true }) },
  { label: '天地图 矢量', style: tiandituStyle('vec', { annotation: true }) }
]

// 同一个值同时绑定底图控件与地图样式：控件只负责选择，地图负责切换
const style = shallowRef(items[0]!.style)
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ style, center: [116.397, 39.908], zoom: 11 }">
      <MaplibreBasemapControl v-model="style" :items="items" position="top-right" />
    </MaplibreMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MaplibreBasemapControl component
 */
interface MaplibreBasemapControlProps {
  /**
   * 候选底图
   */
  items: BasemapItem[];
  /**
   * 控件停靠位置；省略用地图默认位置
   */
  position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
  /**
   * 折叠按钮与选项组的无障碍标签
   * @default 'Basemap'
   */
  label?: string | undefined;
  /**
   * 当前底图样式，与 MaplibreMap 的 options.style 绑定同一个值；按引用或字符串相等判断选中项
   */
  modelValue?: string | StyleSpecification | undefined;
  /**
   * 面板是否展开
   * @default false
   */
  open?: boolean | undefined;
}
```

### Emits

```ts
/**
 * Emitted events for the MaplibreBasemapControl component
 */
interface MaplibreBasemapControlEmits {
  update:modelValue: (payload: [value: string | StyleSpecification | undefined]) => void;
  update:open: (payload: [value: boolean]) => void;
}
```

## Changelog

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


## Sitemap

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