Get Started

vue3-openlayers works with the following versions which must be installed as peer dependencies:

• ol: ^10.0.0
• ol-contextmenu: ^5.4.0
• ol-ext: ^4.0.21
• vue: ^3.4.0

Installation

npm

npm i ol ol-ext ol-contextmenu    # install the peerDependencies
npm i vue3-openlayers             # install this library

yarn

yarn add ol ol-ext ol-contextmenu # install the peerDependencies
yarn add vue3-openlayers          # install this library

pnpm

pnpm add ol ol-ext ol-contextmenu # install the peerDependencies
pnpm add vue3-openlayers          # install this library

bun

bun add ol ol-ext ol-contextmenu  # install the peerDependencies
bun add vue3-openlayers           # install this library

Please ensure you are aware of potential issues with Server-Side-Rendering (SSR).

Usage: As Plugin

To use vue3-openlayers in your application as a Plugin for global component availability, you can import all components (default export) or only parts of vue3-openlayers in your application (named exports).

main.ts (Global Plugin)

import { createApp } from "vue";
import App from "./App.vue";

// The style are only needed for some map controls.
// However, you can also style them by your own
import "vue3-openlayers/styles.css";

import OpenLayersMap from "vue3-openlayers";

const app = createApp(App);

app.use(OpenLayersMap /*, options */);

app.mount("#app");

main.ts (Selective Plugins)

import { createApp } from "vue";
import App from "./App.vue";

// The style are only needed for some map controls.
// However, you can also style them by your own
import "vue3-openlayers/styles.css";

import { Map, Layers, Sources } from "vue3-openlayers";

const app = createApp(App);

app.use(Map /*, options */);
app.use(Layers /*, options */);
app.use(Sources /*, options */);

app.mount("#app");

AppComponent.vue

<script setup lang="ts"></script>

<template>
  <ol-map style="min-width: 400px; height: 400px;">
    <ol-view :center="[40, 40]" :zoom="5" projection="EPSG:4326" />
    <ol-tile-layer>
      <ol-source-osm />
    </ol-tile-layer>
  </ol-map>
</template>

Usage: Explicit import

You can also import and use components individually by importing them directly in your components.

AppComponent.vue

<script setup lang="ts">
import { Map, Layers, Sources } from "vue3-openlayers";
</script>

<template>
  <Map.OlMap style="min-width: 400px; height: 400px;">
    <Map.OlView :center="[40, 40]" :zoom="5" projection="EPSG:4326" />
    <Layers.OlTileLayer>
      <Sources.OlSourceOsm />
    </Layers.OlTileLayer>
  </Map.OlMap>
</template>

Server Side Rendering

Be aware that the Vue3Openlayers map cannot be rendered at server side. Disabling SSR resolves this issue. The following example shows how to disable Vue3Openlayers when running SSR using Nuxt.js.

Example Nuxt config

The first approach is to disable the whole affected route where the map is rendered:

export default defineNuxtConfig({
  // ...
  routeRules: {
    '/sales': { ssr: false },
  },
  // ...
})

You can also specifically render the map only at client side, by putting inside the ClientOnly component:

<template>
  <ClientOnly>
    <Map.OlMap style="min-width: 400px; height: 400px;">
      <Map.OlView :center="[40, 40]" :zoom="5" projection="EPSG:4326"/>
      <Layers.OlTileLayer>
        <Sources.OlSourceOsm/>
      </Layers.OlTileLayer>
    </Map.OlMap>
  </ClientOnly>
</template>

see also: Issue #358

Debug Mode

You can activate the debug mode, to log events receiving from OpenLayers and props passed to OpenLayers on the console.

Plugin Usage

main.ts (Global Plugin)

import { createApp } from "vue";
import App from "./App.vue";

import OpenLayersMap, {
  type Vue3OpenlayersGlobalOptions,
} from "vue3-openlayers";

const app = createApp(App);

const options: Vue3OpenlayersGlobalOptions = {
  debug: true,
};
app.use(OpenLayersMap, options);

app.mount("#app");

main.ts (Selective Plugins)

import { createApp } from "vue";
import App from "./App.vue";

import {
  Map,
  Layers,
  Sources
  type Vue3OpenlayersGlobalOptions
} from 'vue3-openlayers';

const app = createApp(App);

const options: Vue3OpenlayersGlobalOptions = {
  debug: true,
};
app.use(Map, options);
app.use(Layers, options);
app.use(Sources, options);

app.mount("#app");

Provide for components

AppComponent.ts

<script setup lang="ts">
import { provide } from "vue";
import {
  Map,
  Layers,
  Sources,
  type Vue3OpenlayersGlobalOptions,
} from "vue3-openlayers";

const options: Vue3OpenlayersGlobalOptions = {
  debug: true,
};

provide("ol-options", options);
</script>

<template>
  <Map.OlMap style="min-width: 400px; height: 400px">
    <Map.OlView :center="[40, 40]" :zoom="5" projection="EPSG:4326" />
    <Layers.OlTileLayer>
      <Sources.OlSourceOsm />
    </Layers.OlTileLayer>
  </Map.OlMap>
</template>