Skip to content

Get Started

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

Installation

bash
npm i ol ol-ext ol-contextmenu    # install the peerDependencies
npm i vue3-openlayers             # install this library
bash
yarn add ol ol-ext ol-contextmenu # install the peerDependencies
yarn add vue3-openlayers          # install this library
bash
pnpm add ol ol-ext ol-contextmenu # install the peerDependencies
pnpm add vue3-openlayers          # install this library
bash
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).

ts
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");
ts
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");
vue
<script setup lang="ts"></script>

<template>
  <ol-map style="min-width: 400px; min-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.

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

<template>
  <Map.OlMap style="min-width: 400px; min-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:

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

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

vue
<template>
  <ClientOnly>
    <Map.OlMap style="min-width: 400px; min-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

ts
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");
ts
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

vue
<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; min-height: 400px">
    <Map.OlView :center="[40, 40]" :zoom="5" projection="EPSG:4326" />
    <Layers.OlTileLayer>
      <Sources.OlSourceOsm />
    </Layers.OlTileLayer>
  </Map.OlMap>
</template>