---
title: "MaplibreControl"
description: "Generic control container that places any Vue content in a map control slot, optionally collapsed into an icon button."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/controls/control"
---
# MaplibreControl

> Generic control container that places any Vue content in a map control slot, optionally collapsed into an icon button.

## Introduction

`MaplibreControl` mounts its slot content into a MapLibre control slot (docked in a corner alongside the built-in controls). The content stays in the Vue component tree, so it can use reactive state and the injected map context directly. `MaplibreLayerControl`, `MaplibreBasemapControl` and `MaplibreLegend` are built on it.

- **Collapsible**: with `collapsible`, it collapses into the icon button from the `#trigger` slot and expands on click. The close button in the panel's top-right corner or Esc collapses it, and so does an outside click when `dismissible` is true.
- **State**: `v-model:open` can be controlled; when unbound the component keeps its own state.

> [!NOTE]
> 
> Buttons inside the control are affected by the MapLibre control group styles (
> 
> .maplibregl-ctrl-group button
> 
>  is a fixed 29px square). When styling your own buttons, use a selector at least as specific, or set 
> 
> :group="false"
> 
>  to drop the control group styles.

## Usage

A persistent control in the top-left corner and a collapsible one in the top-right:

```vue [ControlExample.vue]
<script setup lang="ts">
const zoom = ref(11)
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap v-model:zoom="zoom" :options="{ style: 'https://tiles.openfreemap.org/styles/liberty', center: [116.397, 39.908] }">
      <!-- 常驻控件：任意 Vue 内容，可直接读取响应式状态 -->
      <MaplibreControl position="top-left">
        <div class="px-2 py-1 text-xs tabular-nums">
          Zoom {{ zoom.toFixed(1) }}
        </div>
      </MaplibreControl>
      <!-- 可折叠控件：收起为图标按钮，点击展开 -->
      <MaplibreControl position="top-right" collapsible label="说明">
        <template #trigger>
          <UIcon name="i-lucide-info" class="size-4" />
        </template>
        <p class="w-44 text-xs">
          MaplibreControl 把任意 Vue 内容放进地图控件槽位，点击外部、按 Esc 或右上角按钮收起。
        </p>
      </MaplibreControl>
    </MaplibreMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MaplibreControl component
 */
interface MaplibreControlProps {
  /**
   * 控件停靠位置；省略用地图默认位置
   */
  position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
  /**
   * 是否使用 maplibre 控件组样式（白底圆角卡片）
   * @default true
   */
  group?: boolean | undefined;
  /**
   * 是否可折叠：收起时只显示触发按钮，点击展开，面板内关闭按钮或 Esc 收起
   * @default false
   */
  collapsible?: boolean | undefined;
  /**
   * 可折叠时点击控件外部是否收起；常驻展示的内容（如图例）应关闭
   * @default true
   */
  dismissible?: boolean | undefined;
  /**
   * 折叠按钮的无障碍标签
   */
  label?: string | undefined;
  /**
   * 可折叠时的展开状态
   * @default false
   */
  open?: boolean | undefined;
}
```

### Emits

```ts
/**
 * Emitted events for the MaplibreControl component
 */
interface MaplibreControlEmits {
  update:open: (payload: [value: boolean]) => void;
}
```

### Slots

```ts
/**
 * Slots for the MaplibreControl component
 */
interface MaplibreControlSlots {
  /**
   * 控件内容；可折叠时为展开后的面板
   */
  default(): any;
  /**
   * 折叠按钮内容（通常是图标）
   */
  trigger(): any;
}
```

## Changelog

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


## Sitemap

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