---
title: "useMapAnimation"
description: "Map frame-animation primitive built on requestAnimationFrame; invokes the frame callback only when the map exists and the style is loaded."
canonical_url: "https://mapbox.mhaibaraai.cn/en/docs/composables/use-map-animation"
---
# useMapAnimation

> Map frame-animation primitive built on requestAnimationFrame; invokes the frame callback only when the map exists and the style is loaded.

## Introduction

`useMapAnimation` is a map frame-animation primitive built on `useRafFn` (automatically stopped when the component unmounts). It invokes the `frame` callback only when the map exists and the style is loaded. The second argument to the callback is the elapsed milliseconds since the animation started. Animated effect components and frame-driven images all share this primitive. Returns `pause`, `resume`, and `isActive` to control the animation state.

> [!NOTE]
> 
> When used outside a 
> 
> <MapboxMap>
> 
>  subtree, specify the target map via 
> 
> options.mapId
> 
> . The callback runs every frame — avoid creating new objects or doing heavy computation inside it.

## Usage

Drive a periodic `circle-radius` pulse on every frame:

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

const mapId = 'use-map-animation-demo'

const data: FeatureCollection = {
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', properties: {}, geometry: { type: 'Point', coordinates: [116.397, 39.908] } }
  ]
}

// 每帧驱动 circle-radius 周期脉动；图层未就绪时跳过
useMapAnimation((map, elapsed) => {
  if (!map.getLayer('pulse')) return
  map.setPaintProperty('pulse', 'circle-radius', 14 + 8 * Math.sin(elapsed / 400))
}, { mapId })
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MapboxMap :map-id="mapId" :options="{ style: 'mapbox://styles/mapbox/dark-v11', center: [116.397, 39.908], zoom: 12 }">
      <MapboxLayer
        layer-id="pulse"
        type="circle"
        :source="{ type: 'geojson', data }"
        :paint="{ 'circle-color': '#22d3ee', 'circle-opacity': 0.6, 'circle-radius': 14 }"
      />
    </MapboxMap>
  </div>
</template>
```

## API

### `useMapAnimation()`

Creates a frame animation loop.

**frame** (`(map: Map, elapsedMs: number) => void`) *required*: Per-frame callback; elapsedMs is the elapsed milliseconds since the animation started.

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

**options.immediate** (`boolean`): Start immediately after creation, defaults to true.

Returns `UseMapAnimationReturn`:

**pause** (`() => void`): Pauses the animation.

**resume** (`() => void`): Resumes the animation.

**isActive** (`Readonly<Ref<boolean>>`): Whether the animation is currently running.

## Changelog

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


## Sitemap

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