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

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

## Introduction

`MapboxTooltip` 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">
    <MapboxMap :options="{ style: 'mapbox://styles/mapbox/light-v11', center: [116.39, 39.93], zoom: 11 }">
      <MapboxLayer
        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 暴露命中要素 -->
      <MapboxTooltip 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>
      </MapboxTooltip>
    </MapboxMap>
  </div>
</template>
```

## `trigger` `v1.2.0+`

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">
    <MapboxMap :options="{ style: 'mapbox://styles/mapbox/light-v11', center: [116.39, 39.93], zoom: 11 }">
      <MapboxLayer
        layer-id="poi"
        type="circle"
        :source="{ type: 'geojson', data }"
        :paint="{ 'circle-radius': 9, 'circle-color': '#f43f5e', 'circle-stroke-width': 2, 'circle-stroke-color': '#fff' }"
      />
      <MapboxTooltip 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>
      </MapboxTooltip>
    </MapboxMap>
  </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 
> 
> MapboxPopup
> 
> .

## API

### Props

```ts
/**
 * Props for the MapboxTooltip component
 */
interface MapboxTooltipProps {
  /**
   * 目标图层 id
   */
  layerId: string;
  /**
   * Popup 选项（hover 模式下 closeButton/closeOnClick 由组件接管）
   */
  options?: mapboxgl.PopupOptions | undefined;
  /**
   * 悬浮时鼠标指针样式
   * @default "\"pointer\""
   */
  cursor?: string | undefined;
  /**
   * 触发时机；'none' 表示不绑定任何监听，可用于临时停用
   * @default "\"hover\""
   */
  trigger?: PopupTrigger | undefined;
}
```

### Slots

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

### Expose

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

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sBMFI">
          hovered
        </span>
      </code>
    </td>
    
    <td>
      <code className="language-ts-type shiki shiki-themes material-theme-lighter material-theme material-theme-palenight" language="ts-type" style="">
        <span class="sMK4o">
          ()
        </span>
        
        <span class="spNyl">
          =>
        </span>
        
        <span class="sBMFI">
          GeoJSONFeature
        </span>
        
        <span class="sMK4o">
          |
        </span>
        
        <span class="sBMFI">
          undefined
        </span>
      </code>
      
       <br />
      
       <p>
        The currently active feature
      </p>
    </td>
  </tr>
</tbody>
</table>

## Changelog

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


## Sitemap

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