---
title: "useMeasure"
description: "Distance and area measurement tool that manages its own geojson source and layers, computing live readouts with turf."
canonical_url: "https://mapbox.mhaibaraai.cn/en/docs/composables/use-measure"
---
# useMeasure

> Distance and area measurement tool that manages its own geojson source and layers, computing live readouts with turf.

## Introduction

`useMeasure` provides distance and area measurement interactions: click to add points, move to preview, double-click to finish the current segment, and Escape to cancel. It manages its own GeoJSON source and display layers internally, using turf to compute and format live readouts. Returns `start`, `stop`, and `clear` control methods along with reactive `mode`, `active`, and `result` state.

> [!NOTE]
> 
> When used outside a 
> 
> <MapboxMap>
> 
>  subtree, specify the target map via 
> 
> options.mapId
> 
> . Readout formatting reuses 
> 
> formatDistance / formatArea
> 
> .

## Usage

A toolbar toggles between distance and area measurement; `result` shows the live readout for the current segment:

```vue [UseMeasureExample.vue]
<script setup lang="ts">
const mapId = 'use-measure-demo'

const { start, stop, clear, mode, active, result } = useMeasure({ mapId })
</script>

<template>
  <div class="relative h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MapboxMap :map-id="mapId" :options="{ style: 'mapbox://styles/mapbox/light-v11', center: [116.39, 39.91], zoom: 11 }" />
    <div class="absolute left-2 top-2 z-10 flex gap-1">
      <UButton size="sm" :variant="active && mode === 'distance' ? 'solid' : 'soft'" @click="start('distance')">
        测距
      </UButton>
      <UButton size="sm" :variant="active && mode === 'area' ? 'solid' : 'soft'" @click="start('area')">
        测面
      </UButton>
      <UButton size="sm" variant="soft" :disabled="!active" @click="stop">
        结束
      </UButton>
      <UButton size="sm" color="error" variant="soft" @click="clear">
        清空
      </UButton>
    </div>
    <div v-if="result" class="absolute bottom-2 left-2 z-10 rounded bg-default/90 px-3 py-1.5 text-sm font-medium text-default ring ring-default">
      {{ result }}
    </div>
  </div>
</template>
```

## API

### `useMeasure()`

Creates a measurement tool.

**options.mapId** (`string`): Target map id; required when used outside a <MapboxMap> subtree.

**options.color** (`string`): Primary color, defaults to '#f59e0b'.

Returns `UseMeasureReturn`:

**start** (`(mode: MeasureMode) => void`): Enters measurement mode: click to add points, mousemove to preview, dblclick to finish the current segment.

**stop** (`() => void`): Exits measurement interaction (preserves drawn results).

**clear** (`() => void`): Clears all measurement results.

**mode** (`Ref<MeasureMode | undefined>`): Current measurement mode.

**active** (`Ref<boolean>`): Whether measurement is active.

**result** (`Ref<string>`): Formatted readout for the current segment (including cursor preview).

### `MeasureMode`

Measurement mode: `'distance'` | `'area'`.

## Changelog

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


## Sitemap

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