---
title: "useMap"
description: "Inject the current MapboxMap context to access the map instance and loading state from any descendant component."
canonical_url: "https://mapbox.mhaibaraai.cn/en/docs/composables/use-map"
---
# useMap

> Inject the current MapboxMap context to access the map instance and loading state from any descendant component.

## Introduction

`useMap` injects the context provided by the nearest `<MapboxMap>`, returning a reference to the map instance, the style-loaded state, and a ready callback. It is the unified entry point for all declarative child components to access the map, without requiring an id lookup.

> [!NOTE]
> 
> Must be called inside a 
> 
> <MapboxMap>
> 
>  subtree, otherwise it will throw. To access the map outside the component tree, use 
> 
> useMapbox
> 
>  instead.

`onReady` re-runs on every `setStyle` call as well as the initial style load, making it the recommended place to create sources, layers, and bind events. `map` is `undefined` during SSR and before mount — the component handles SSR safety internally.

## Usage

A child component reads live camera state (center, zoom, loaded) via `useMap()`:

```vue [UseMapExample.vue]
<script setup lang="ts">
import { defineComponent, h, ref } from 'vue'

// 子组件位于 <MapboxMap> 子树内，经 useMap() 注入上下文读取实时相机状态
const MapStatus = defineComponent({
  name: 'MapStatus',
  setup() {
    const { isLoaded, onReady } = useMap()
    const center = ref('')
    const zoom = ref(0)

    onReady((map) => {
      const sync = () => {
        const c = map.getCenter()
        center.value = `${c.lng.toFixed(3)}, ${c.lat.toFixed(3)}`
        zoom.value = Number(map.getZoom().toFixed(2))
      }
      sync()
      map.on('move', sync)
    })

    return () => h('div', { class: 'absolute left-2 top-2 z-10 space-y-0.5 rounded bg-default/90 px-3 py-2 text-xs text-default ring ring-default' }, [
      h('div', `样式就绪：${isLoaded.value ? '是' : '否'}`),
      h('div', `中心：${center.value}`),
      h('div', `缩放：${zoom.value}`)
    ])
  }
})
</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.397, 39.908], zoom: 10 }">
      <MapStatus />
    </MapboxMap>
  </div>
</template>
```

## API

### `useMap()`

Injects the current map context and returns `MapboxContext`. No parameters.

Returns `MapboxContext`:

**id** (`string`): The map id; auto-generated when not explicitly set.

**map** (`ShallowRef<Map | undefined>`): Reference to the map instance; undefined during SSR and before mount.

**isLoaded** (`Ref<boolean>`): Whether the map style has finished loading.

**whenLoaded** (`() => Promise<Map>`): Resolves when the style has loaded for the first time, returning the map instance.

**onReady** (`(cb: (map: Map) => void) => () => void`): Executes the callback when the style is ready, and re-runs it after each setStyle reload (for rebuilding sources and layers). Returns an unsubscribe function.

## Changelog

See commit history for [src/runtime/composables/useMap.ts](https://github.com/mhaibaraai/movk-mapbox/commits/main/src/runtime/composables/useMap.ts).


## Sitemap

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