---
title: "useMapExport"
description: "Export the current map as an image dataURL or trigger a browser download, reading the canvas inside the render callback without preserveDrawingBuffer."
canonical_url: "https://mapbox.mhaibaraai.cn/en/docs/composables/use-map-export"
---
# useMapExport

> Export the current map as an image dataURL or trigger a browser download, reading the canvas inside the render callback without preserveDrawingBuffer.

## Introduction

`useMapExport` exports the current map as an image: `exportImage` returns a dataURL, and `download` triggers a browser download directly. It reads the canvas synchronously inside the `render` callback, so `preserveDrawingBuffer` does not need to be enabled on the map (the WebGL buffer is cleared after each frame render, so `toDataURL` must be called at that exact moment).

> [!NOTE]
> 
> When used outside a 
> 
> <MapboxMap>
> 
>  subtree, specify the target map via 
> 
> options.mapId
> 
> . Exporting maps that include third-party tiles may be subject to cross-origin canvas taint restrictions.

## Usage

Capture a preview screenshot and download as PNG:

```vue [UseMapExportExample.vue]
<script setup lang="ts">
const mapId = 'use-map-export-demo'

const preview = ref('')
const { exportImage, download } = useMapExport({ mapId })

async function snapshot() {
  preview.value = await exportImage()
}
</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.397, 39.908], zoom: 11 }" />
    <div class="absolute left-2 top-2 z-10 flex gap-1">
      <UButton size="sm" @click="snapshot">
        截图预览
      </UButton>
      <UButton size="sm" variant="soft" @click="download({ fileName: 'map.png' })">
        下载 PNG
      </UButton>
    </div>
    <img v-if="preview" :src="preview" alt="地图截图" class="absolute bottom-2 right-2 z-10 h-28 rounded ring ring-default">
  </div>
</template>
```

## API

### `useMapExport()`

Creates an export helper.

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

Returns `UseMapExportReturn`:

**exportImage** (`(options?: ExportImageOptions) => Promise<string>`): Exports the current map view as a dataURL.

**download** (`(options?: DownloadOptions) => Promise<void>`): Exports the map and triggers a browser file download.

### `ExportImageOptions`

**format** (`'image/png' | 'image/jpeg' | 'image/webp'`): Image format, defaults to 'image/png'.

**quality** (`number`): Quality for lossy formats, range 0–1, defaults to 0.92.

### `DownloadOptions`

Extends `ExportImageOptions` with:

**fileName** (`string`): Download file name, defaults to 'map.png'.

## Changelog

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


## Sitemap

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