---
title: "How to display a map in Vue.js using MapLibre GL JS | Vuejs | Maplibre gl js"
description: "Create a Vue.js component for rendering MapLibre GL maps."
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# How to display a map in Vue.js using MapLibre GL JS

In this step-by-step tutorial, you’ll learn how to create a Vue.js component to render a map using MapLibre GL JS. Together we will make a simple full-screen map application, serving as a practical example of how to seamlessly integrate MapTiler maps with MapLibre GL JS into your Vue.js app.

By the end of this tutorial, you will be able to create a full-screen map with a marker placed at a specified location. Your final map will look like this:

![Display a map in Vue.js using MapLibre GL JS](final_map.webp)

## Getting started

_Minimal requirements for completing this tutorial._

-   **Some experience with Vue.js** You don’t need a lot of experience using [Vue.js](https://vuejs.org/) for this tutorial, but you should be familiar with basic concepts and workflow.
    
-   **MapTiler API key.** Your MapTiler account access key is on your MapTiler [Cloud](https://cloud.maptiler.com/account/keys) account page or [Get API key for FREE](https://cloud.maptiler.com/account/keys).
    
-   **MapLibre GL JS.** JavaScript library for building web maps. In this tutorial, you will learn how to install it.
    
-   **Node.js and npm.** Necessary to run your Vue.js app locally. [Node.js](https://nodejs.org/en/)
    
-   **Vue CLI.** You need to have the [Vue CLI](https://cli.vuejs.org/) installed. To install the Vue CLI, open a terminal window and run the following command:
    

```bash
npm install -g @vue/cli
```

## Create an app

In this step, we are going to learn how to create a Vue.js app.

To create a new Vue.js project, run in your command-line:

```bash
vue create my-vue-map
```

The `vue create` command prompts you for information about features to include in the initial app. Select the `Default (Vue 3) ([Vue 3] babel, eslint)` option.

![Vue.js CLI options](vuejs-options.png)

Use the arrow keys and press the Enter or Return key to select an option. The Vue CLI installs the necessary Vue.js npm packages and other dependencies and creates a new workspace and a simple Welcome app, ready to run. For more information, follow [Creating a Project](https://cli.vuejs.org/guide/creating-a-project.html#vue-create).

Navigate to the newly created project folder `my-vue-map`

```bash
cd my-vue-map
```

Inside the newly created project folder, run `npm run serve` to start your local environment. You will find your app running on the address `http://localhost:8080/`.

Now you should see the app in your browser.

![Vue.js app](vuejs.png)

### Installation and setting up

To install MapLibre GL library, navigate to your project folder and run the command:

```bash
npm i maplibre-gl
```

Navigate to the `src` folder and delete all the content of the `App.vue` file. Write the following lines in the `App.vue` file

```html
<template>
  <div class="app">This is my map App</div>
</template>

<script>
  export default {
    name: "App",
    components: {},
  };
</script>

<style>
  body {
    margin: 0;
    font-family:
      -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen",
      "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue",
      sans-serif;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
  }

  code {
    font-family:
      source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace;
  }

  .app {
    text-align: center;
  }
</style>
```

Now you should see “This is my map App“ in your browser.

Navigate to the `src/components` folder and delete de `HelloWorld.vue` file

### Create a navbar component

In this step, we will create a simple heading navbar component.

Create a new file called `Navbar.vue` inside the `components` folder and write these lines:

```html
<template>
  <div class="heading">
    <h1>This is my map App</h1>
  </div>
</template>

<script>
  export default {
    name: "Navbar",
  };
</script>

<style scoped>
  .heading {
    margin: 0;
    padding: 0px;
    background-color: black;
    color: white;
  }

  .heading > h1 {
    padding: 20px;
    margin: 0;
  }
</style>
```

Finally, to display the `Navbar` we need to import the Navbar component and add it to our main component template section `App.vue`.

Import the navbar component into `App.vue` script block

```html
<script>
  import Navbar from './components/Navbar.vue';

  export default {
    name: 'App',
    components: {
      Navbar
    }
  }
</script>
```

Replace the text _This is my map App_ with `<Navbar />`. Your `App.vue` file should look like this:

```html
<template>
  <div class="app">
    <Navbar />
  </div>
</template>

<script>
import Navbar from './components/Navbar.vue';

export default {
  name: 'App',
  components: {
    Navbar
  }
}
</script>

<style>
body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

code {
  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
    monospace;
}

.app {
  text-align: center;
}
</style>
```

Now you should see the black navbar at the top of your browser.

![App navigation bar](navbar.png)

### Create a map component

In this step, we will create a simple map component.

Create a new file called `Map.vue` inside the `components` folder and write these lines:

```html
<template>
  <div class="map-wrap">
    <a href="https://www.maptiler.com" class="watermark"><img
        src="https://api.maptiler.com/resources/logo.svg" alt="MapTiler logo"/></a>
    <div class="map" ref="mapContainer"></div>
  </div>
</template>

<script>
import { Map } from 'maplibre-gl';
import { shallowRef, onMounted, onUnmounted, markRaw } from 'vue';

export default {
  name: "Map",
  setup () {
    const mapContainer = shallowRef(null);
    const map = shallowRef(null);

    onMounted(() => {
      const apiKey = 'YOUR_MAPTILER_API_KEY_HERE';

      const initialState = { lng: 139.753, lat: 35.6844, zoom: 14 };

      map.value = markRaw(new Map({
        container: mapContainer.value,
        style: `https://api.maptiler.com/maps/streets-v4/style.json?key=${apiKey}`,
        center: [initialState.lng, initialState.lat],
        zoom: initialState.zoom
      }));

    }),
    onUnmounted(() => {
      map.value?.remove();
    })

    return {
      map, mapContainer
    };
  }
};
</script>

<style scoped>
@import '~maplibre-gl/dist/maplibre-gl.css';

.map-wrap {
  position: relative;
  width: 100%;
  height: calc(100vh - 77px); /* calculate height of the screen minus the heading */
}

.map {
  position: absolute;
  width: 100%;
  height: 100%;
}

.watermark {
  position: absolute;
  left: 10px;
  bottom: 10px;
  z-index: 999;
}
</style>
```

We use `position: absolute` on the map itself and `position: relative` on the wrap around the map for more possibilities in future styling.

Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [secure the key](https://docs.maptiler.com/guides/credentials/api-key/#secure-key) before you publish it.

1.  The `container` option sets the DOM element in which the map will be rendered. We will assign the `mapContainer` ref expected by our component to an HTML element, which will act as a container. Keep in mind that the reference to `mapContainer` can only be used after the execution of the `onMounted` hook.
    
2.  The `style` option defines what style is the map going to use.
    
3.  The `center` and `zoom` options set the starting position of the map.
    
4.  The `onUnmounted` function does the cleanup that should occur when the instance is destroyed.
    

### Render a map

Finally, to display the `Map` we need to import the Map component and add it to our main component `App.vue`.

Import the map component into `App.vue` script block

```html
<script>
import Navbar from './components/Navbar.vue';
import Map from './components/Map.vue';

export default {
  name: 'App',
  components: {
    Navbar,
    Map
  }
}
</script>
```

Add the `<Map />` just below the Navbar in the template section. The template block should look like this

```html
<template>
  <div class="app">
    <Navbar />
    <Map />
  </div>
</template>
```

With everything done up until now, you should be able to see your beautiful map in your browser.

![Full-screen map](map.webp)

Your `App.vue` file should look like this:

```html
<template>
  <div class="app">
    <Navbar />
    <Map />
  </div>
</template>

<script>
import Navbar from './components/Navbar.vue';
import Map from './components/Map.vue';

export default {
  name: 'App',
  components: {
    Navbar,
    Map
  }
}
</script>

<style>
body {
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
    'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
    sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

code {
  font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
    monospace;
}

.app {
  text-align: center;
}
</style>
```

### Basic additional options

The last topic of this tutorial will be adding basic objects to your map. For more detailed information you can visit the [MapLibre documentation](https://maplibre.org/maplibre-gl-js/docs/API/#markers-and-controls).

### Map Controls

We will navigate back to our `Map.vue` file and add map [navigation controls](https://maplibre.org/maplibre-gl-js/docs/API/classes/NavigationControl/) to our map.

Add the `NavigationControl` next to the Map object import from MapLibre GL.

```js
import { Map, NavigationControl } from 'maplibre-gl';
```

On line 30 (just after the initialization of the map) of the `Map.vue` file, add the following line:

```js
map.value.addControl(new NavigationControl(), 'top-right');
```

`new NavigationControl()` will create a new controls object which we add to the current map using the `addControl()` function in the `'top-right'` position.

![Map navigation control](nav_control.webp)

### Map marker

Another basic thing to add to your map could be a [marker](https://maplibre.org/maplibre-gl-js/docs/API/classes/Marker/) of some location.

Add the `Marker` next to the Map object import from MapLibre GL.

```js
import { Map, NavigationControl, Marker } from 'maplibre-gl';
```

In the following line where we declare the navigation control, we add these lines:

```js
new Marker({color: "#FF0000"})
  .setLngLat([139.7525,35.6846])
  .addTo(map);
```

We create a new marker using the `Marker` function. We added the color option to make it red, then set Lng/Lat of the marker using `.setLngLat()` function, and finally added it to the current map using `.addTo()` function.

We are finished with our basic map objects, your `Map.vue` file should look like this:

```html
<template>
  <div class="map-wrap">
    <a href="https://www.maptiler.com" class="watermark"><img
        src="https://api.maptiler.com/resources/logo.svg" alt="MapTiler logo"/></a>
    <div class="map" ref="mapContainer"></div>
  </div>
</template>

<script>
import { Map, NavigationControl, Marker } from 'maplibre-gl';
import { shallowRef, onMounted, onUnmounted, markRaw } from 'vue';

export default {
  name: "Map",
  setup () {
    const mapContainer = shallowRef(null);
    const map = shallowRef(null);

    onMounted(() => {
      const apiKey = 'YOUR_MAPTILER_API_KEY_HERE';

      const initialState = { lng: 139.753, lat: 35.6844, zoom: 14 };

      map.value = markRaw(new Map({
        container: mapContainer.value,
        style: `https://api.maptiler.com/maps/streets-v4/style.json?key=${apiKey}`,
        center: [initialState.lng, initialState.lat],
        zoom: initialState.zoom
      }));
      map.value.addControl(new NavigationControl(), 'top-right');
      new Marker({color: "#FF0000"})
        .setLngLat([139.7525,35.6846])
        .addTo(map.value);
    }),
    onUnmounted(() => {
      map.value?.remove();
    })

    return {
      map, mapContainer
    };
  }
};
</script>

<style scoped>
@import '~maplibre-gl/dist/maplibre-gl.css';

.map-wrap {
  position: relative;
  width: 100%;
  height: calc(100vh - 77px); /* calculate height of the screen minus the heading */
}

.map {
  position: absolute;
  width: 100%;
  height: 100%;
}

.watermark {
  position: absolute;
  left: 10px;
  bottom: 10px;
  z-index: 999;
}
</style>
```

![Display MapLibre GL JS map using React JS](final_map.webp)

### Full code to download

We have created a template with the result of this tutorial that will serve as a basis to build future applications. You can access the template repository at ![GitHubLogo](https://docs.maptiler.com/assets/img/github.svg)[Vue.js template for MapLibre](https://github.com/maptiler/vue-template-maplibre-gl-js).

### Online demo:

You can see an online demo at [https://labs.maptiler.com/vue-template-maplibre-gl-js/](https://labs.maptiler.com/vue-template-maplibre-gl-js/)

## Conclusion

Congratulations! You have finished your simple full-screen map app using Vue.js, showing Tokyo with a marker on Tokyo Imperial Palace. You can explore more about MapLibre GL JS for your map in the [MapLibre API reference](https://maplibre.org/maplibre-gl-js/docs/API/).

## Useful links

[MapTiler - JavaScript Maps API](https://docs.maptiler.com/sdk-js/)

[Vue.js](https://vuejs.org/)

[NPM - MapLibre GL](https://www.npmjs.com/package/maplibre-gl)

[MapLibre official web](https://maplibre.org/)

[MapTiler - Map Designer](https://www.maptiler.com/cloud/customize/)

## Learn more

### Vue.js with MapTiler maps

If you’re looking to develop Vue.js applications with MapTiler SDK JS, check out our tutorial titled [Vue.js with MapTiler maps](https://docs.maptiler.com/vuejs/). This step-by-step tutorial will provide you with the necessary guidance and examples to create a Vue.js component that leverages the power of MapTiler SDK JS mapping library to render maps.