---
title: "MaplibreProjection"
description: "Switch the map projection to a 3D globe, with zoom-interpolated transitions between globe and flat views."
canonical_url: "https://maplibre.mhaibaraai.cn/en/docs/environment/projection"
---
# MaplibreProjection

> Switch the map projection to a 3D globe, with zoom-interpolated transitions between globe and flat views.

## Introduction

`MaplibreProjection` calls `setProjection` to set the map projection. `type` defaults to `'globe'` and also accepts `'mercator'`, `'vertical-perspective'` or a zoom-interpolated expression; `options` forwards a full projection specification and takes precedence over `type`. The projection is reapplied after a basemap switch (`setStyle`), and unmounting restores the projection that was active before the component took over.

> [!NOTE]
> 
> A projection can come from three places: the style's 
> 
> projection
> 
>  field, 
> 
> MaplibreProjection
> 
> , and 
> 
> MaplibreGlobeControl
> 
> . Once mounted, the component overrides the style declaration and restores it on unmount (mercator when the style declares none). Toggling the control does not write back to the component; the component value wins again on the next style reload or props change. Mount only one 
> 
> MaplibreProjection
> 
>  per map.

## Usage

Show the globe at low zoom, with the `atmosphere-blend` of `MaplibreSky` rendering the atmosphere glow:

```vue [ProjectionExample.vue]
<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ style: 'https://tiles.openfreemap.org/styles/liberty', center: [105, 30], zoom: 1.5 }">
      <MaplibreProjection />
      <MaplibreSky
        :options="{
          'sky-color': '#199EF3',
          'horizon-color': '#f0f8ff',
          'atmosphere-blend': ['interpolate', ['linear'], ['zoom'], 0, 1, 5, 1, 7, 0]
        }"
      />
    </MaplibreMap>
  </div>
</template>
```

## Examples

### Zoom transition

Use an interpolation expression for `type` to show a globe when zoomed out and blend smoothly into a flat map when zoomed in:

```vue [ProjectionTransitionExample.vue]
<script setup lang="ts">
import type { ProjectionDefinitionSpecification } from '@maplibre/maplibre-gl-style-spec'

// zoom 10 以下为球体，10~12 之间平滑过渡为平面墨卡托
const type: ProjectionDefinitionSpecification = ['interpolate', ['linear'], ['zoom'], 10, 'vertical-perspective', 12, 'mercator']
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ style: 'https://tiles.openfreemap.org/styles/positron', center: [116.39, 39.91], zoom: 3 }">
      <MaplibreProjection :type="type" />
      <MaplibreNavigationControl position="top-right" />
    </MaplibreMap>
  </div>
</template>
```

### Style declaration

A `projection` declared in the style works without the component; mounting the component overrides it temporarily and unmounting restores it:

```vue [ProjectionStyleExample.vue]
<script setup lang="ts">
import type { StyleSpecification } from 'maplibre-gl'

const flat = ref(false)

// 样式自带 globe 投影；组件挂载时覆盖为 mercator，卸载后还原样式原值
const style: StyleSpecification = {
  version: 8,
  projection: { type: 'globe' },
  sources: {},
  layers: [{ id: 'background', type: 'background', paint: { 'background-color': '#0b1026' } }]
}
</script>

<template>
  <div class="h-115 w-full overflow-hidden rounded-(--ui-radius) border border-default">
    <MaplibreMap :options="{ style, center: [105, 30], zoom: 1.5 }">
      <MaplibreTiandituLayer layer="img" />
      <div class="absolute left-3 top-3 z-10">
        <UButton size="xs" color="neutral" variant="solid" @click="flat = !flat">
          {{ flat ? 'Restore style projection' : 'Override with mercator' }}
        </UButton>
      </div>
      <MaplibreProjection v-if="flat" type="mercator" />
    </MaplibreMap>
  </div>
</template>
```

## API

### Props

```ts
/**
 * Props for the MaplibreProjection component
 */
interface MaplibreProjectionProps {
  /**
   * 投影类型：'mercator' / 'globe' / 'vertical-perspective'，或按 zoom 插值的表达式（如 `['interpolate', ['linear'], ['zoom'], 10, 'vertical-perspective', 12, 'mercator']`）
   * @default 'globe'
   */
  type?: ProjectionDefinitionSpecification | undefined;
  /**
   * 完整投影规格，优先级高于 type
   */
  options?: ProjectionSpecification | undefined;
}
```

## Changelog

See commit history for [src/runtime/components/environment/Projection.vue](https://github.com/mhaibaraai/movk-maplibre/commits/main/src/runtime/components/environment/Projection.vue).


## Sitemap

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