---
title: "MaplibreTooltip"
description: "A popup for layer features, triggered on hover or click, exposing the active feature to its slot."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/core/tooltip"
---
# MaplibreTooltip

> A popup for layer features, triggered on hover or click, exposing the active feature to its slot.

## Introduction

`MaplibreTooltip` attaches a popup to features of the `layerId` layer. With the default `trigger="hover"` it follows the cursor and disappears when the cursor leaves. The default slot exposes the hit feature (`feature`) and `close` so you can render its properties. Event delegation is wired at the map level, so the target layer can be mounted after this component and will still be detected.

`trigger` accepts `hover` / `click` / `none`. With `none` no listeners are bound at all, which is useful for temporarily disabling the tooltip while drawing.

## Usage

Hover over circle-layer features to display feature info — use `feature.properties` in the slot:

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

const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: { name: '天安门', type: '地标' }, geometry: { type: 'Point', coordinates: [116.397, 39.908] } },
    { type: 'Feature', properties: { name: '国贸', type: '商圈' }, geometry: { type: 'Point', coordinates: [116.461, 39.909] } },
    { type: 'Feature', properties: { name: '中关村', type: '科技园' }, geometry: { type: 'Point', coordinates: [116.316, 39.983] } }
  ]
}
</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.39, 39.93], zoom: 11 }">
      <MaplibreLayer
        layer-id="poi"
        type="circle"
        :source="{ type: 'geojson', data }"
        :paint="{ 'circle-radius': 9, 'circle-color': '#f43f5e', 'circle-stroke-width': 2, 'circle-stroke-color': '#fff' }"
      />
      <!-- 悬浮 poi 图层要素时跟随显示，slot 暴露命中要素 -->
      <MaplibreTooltip layer-id="poi">
        <template #default="{ feature }">
          <div v-if="feature" class="px-1 text-sm">
            <span class="font-semibold">{{ feature.properties?.name }}</span>
            <span class="text-muted"> · {{ feature.properties?.type }}</span>
          </div>
        </template>
      </MaplibreTooltip>
    </MaplibreMap>
  </div>
</template>
```

## `trigger`

With `trigger="click"` the popup stays open until another feature is clicked or the close button is pressed:

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

const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: { name: '天安门', type: '地标' }, geometry: { type: 'Point', coordinates: [116.397, 39.908] } },
    { type: 'Feature', properties: { name: '国贸', type: '商圈' }, geometry: { type: 'Point', coordinates: [116.461, 39.909] } },
    { type: 'Feature', properties: { name: '中关村', type: '科技园' }, geometry: { type: 'Point', coordinates: [116.316, 39.983] } }
  ]
}
</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.39, 39.93], zoom: 11 }">
      <MaplibreLayer
        layer-id="poi"
        type="circle"
        :source="{ type: 'geojson', data }"
        :paint="{ 'circle-radius': 9, 'circle-color': '#f43f5e', 'circle-stroke-width': 2, 'circle-stroke-color': '#fff' }"
      />
      <MaplibreTooltip layer-id="poi" trigger="click">
        <template #default="{ feature, close }">
          <div v-if="feature" class="w-44 px-1 py-0.5">
            <p class="font-semibold">
              {{ feature.properties?.name }}
            </p>
            <p class="mt-0.5 text-sm text-muted">
              {{ feature.properties?.type }}
            </p>
            <UButton class="mt-2" size="xs" color="neutral" variant="subtle" @click="close">
              收起
            </UButton>
          </div>
        </template>
      </MaplibreTooltip>
    </MaplibreMap>
  </div>
</template>
```

> [!NOTE]
> 
> The 
> 
> click
> 
>  mode provides a close button by default but does 
> 
> not
> 
>  enable 
> 
> closeOnClick
> 
>  — otherwise the popup would be closed immediately by the very click that opened it. Override via 
> 
> options
> 
>  if you need it.

> [!TIP]
> 
> The component holds a single Popup instance, so only one feature's popup is shown at a time. To keep several feature popups open simultaneously, see "Multiple Popups" on 
> 
> MaplibrePopup
> 
> .

## API

### Props

```ts
/**
 * Props for the MaplibreTooltip component
 */
interface MaplibreTooltipProps {
  /**
   * 目标图层 id；变化时改绑到新图层
   */
  layerId: string;
  /**
   * Popup 选项（hover 模式下 closeButton/closeOnClick 由组件接管）；值变化时重建弹窗
   */
  options?: PopupOptions | undefined;
  /**
   * 悬浮时鼠标指针样式
   * @default 'pointer'
   */
  cursor?: string | undefined;
  /**
   * 触发时机；'none' 表示不绑定任何监听，可用于临时停用
   * @default 'hover'
   */
  trigger?: "click" | "hover" | "none" | undefined;
}
```

### Slots

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

### Expose

Access the component instance via [`useTemplateRef`](https://vuejs.org/api/composition-api-helpers.html#usetemplateref).

| Name | Type |
| --- | --- |
| `hovered` | `() => GeoJSONFeature \| undefined` <br> The currently active feature |

## Changelog

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


## Sitemap

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