---
title: "useMapboxImage"
description: "Register a named image for symbol layers; it is re-added after setStyle and removed on unmount, with an SDF option for tintable icons."
canonical_url: "https://mapbox.mhaibaraai.cn/en/docs/composables/use-mapbox-image"
---
# useMapboxImage

> Register a named image for symbol layers; it is re-added after setStyle and removed on unmount, with an SDF option for tintable icons.

## Introduction

`useMapboxImage` loads a remote image and registers it as a style image, making it available for symbol layers via `icon-image`. After `setStyle` clears all style images, it is automatically re-added via `onReady`; it is removed when the component unmounts. The returned `loaded` state lets you show placeholder feedback while the image is loading.

> [!NOTE]
> 
> Set 
> 
> sdf: true
> 
>  to register the image as an SDF icon, which can then be tinted via 
> 
> icon-color
> 
> . When used outside a 
> 
> <MapboxMap>
> 
>  subtree, specify the target map via 
> 
> options.mapId
> 
> .

## Usage

Register a remote image and reference it from a symbol layer via `icon-image`:

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

const mapId = 'use-mapbox-image-demo'

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

const { loaded } = useMapboxImage('demo-cat', 'https://docs.mapbox.com/mapbox-gl-js/assets/cat.png', { 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.397, 39.908], zoom: 13 }">
      <MapboxLayer
        v-if="loaded"
        layer-id="cats"
        type="symbol"
        :source="{ type: 'geojson', data }"
        :layout="{ 'icon-image': 'demo-cat', 'icon-size': 0.25, 'icon-allow-overlap': true }"
      />
    </MapboxMap>
    <div class="absolute left-2 top-2 z-10 rounded bg-default/90 px-2 py-1 text-xs text-default ring ring-default">
      图片加载：{{ loaded ? '完成' : '加载中…' }}
    </div>
  </div>
</template>
```

## API

### `useMapboxImage()`

Registers a named image.

**name** (`string`) *required*: The name to register the image under, used as the icon-image value.

**url** (`string`) *required*: URL of the image to load.

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

**options.sdf** (`boolean`): Register as an SDF icon (tintable via icon-color).

**options.pixelRatio** (`number`): Pixel density ratio, defaults to 1.

Returns `{ loaded: Ref<boolean> }`: whether the image has finished loading.

## Changelog

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


## Sitemap

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