Getting Started with the Vue Maps Component in Vue 3

18 Nov 20186 minutes to read

This guide provides a step-by-step walkthrough for setting up a Vite project with JavaScript and integrating the Syncfusion® Vue Maps component using the Composition API / Options API. By the end, you’ll have a working Maps component displaying geographic data with legends, tooltips, and data labels.

Choosing Between Composition API and Options API

Vue 3 supports two patterns for organizing component logic:

  • Composition API (<script setup>) - A modern, function-based approach that helps organize related logic into reusable functions and improves code maintainability.
  • Options API - Traditional, object-based approach with separate sections for data, methods, computed properties, and lifecycle hooks. Familiar for developers transitioning from Vue 2.

Prerequisites

Ensure that the development environment meets the required criteria listed in System requirements for Syncfusion® Vue UI components.

Set Up the Vite Project

Vite provides a lightweight, fast development environment for Vue 3 projects. To create a new Vite project, run one of the following commands:

npm

npm create vite@latest

yarn

yarn create vite

Follow the interactive prompts to complete the setup:

Step 1: Project name - Enter my-project (or your preferred name):

? Project name: » my-project

Step 2: Framework selection - Select Vue:

? Select a framework: » - Use arrow-keys. Return to submit.
Vanilla
> Vue
  React
  Preact
  Lit
  Svelte
  Others

Step 3: Variant selection - Choose JavaScript:

? Select a variant: » - Use arrow-keys. Return to submit.
> JavaScript
  TypeScript
  Customize with create-vue ↗
  Nuxt ↗

Step 4: Install dependencies - After the project is created, the CLI prompts you to install dependencies and start the development server:

? Install with <package-manager> and start now?
❯ Yes / No

Select Yes. The CLI automatically navigates to the project directory, installs all required dependencies, and starts the development server.

After setup completes, add Syncfusion® components to the project.

Add Syncfusion® Vue Packages

Syncfusion® Vue component packages are available at npmjs.com. Install the required npm package to use Syncfusion components.

This guide uses the Vue Maps component as an example. Install the @syncfusion/ej2-vue-maps package using either npm or Yarn:

npm

npm install @syncfusion/ej2-vue-maps

yarn

yarn add @syncfusion/ej2-vue-maps

Note: npm v5+ saves packages to dependencies by default; --save is not required.

Add Syncfusion® Vue Maps Component

Step 1: Import and register the Maps component and its child directives in the src/App.vue file. The import structure differs slightly between the two APIs:

  • Composition API: Use the <script setup> syntax.
  • Options API: Register the component and directives using the components option.
<script setup>
  import { MapsComponent as EjsMaps, LayersDirective as ELayers, LayerDirective as ELayer, MapAjax } from '@syncfusion/ej2-vue-maps';
</script>
<script>
import { MapsComponent, LayersDirective, LayerDirective, MapAjax } from '@syncfusion/ej2-vue-maps'
// Component registration
export default {
  name: "App",
  components: {
    'ejs-maps' : MapsComponent,
    'e-layers' : LayersDirective,
    'e-layer' : LayerDirective
  }
}
</script>

Step 2: Declare the property values referenced in the template:

<script setup>
    const shapeData = new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json');
</script>
<script>
data() {
  return {
    shapeData: new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json'),
  };
}
</script>

Step 3: Define the Maps component template and bind the shapeData property to the layer:

<template>
   <ejs-maps>
        <e-layers>
            <e-layer :shapeData='shapeData'></e-layer>
        </e-layers>
    </ejs-maps>
</template>

Here is the complete code combining all steps in the src/App.vue file:

<template>
    <ejs-maps>
        <e-layers>
            <e-layer :shapeData='shapeData'></e-layer>
        </e-layers>
    </ejs-maps>
</template>

<script setup>
import { MapsComponent as EjsMaps, LayersDirective as ELayers, LayerDirective as ELayer, MapAjax } from '@syncfusion/ej2-vue-maps';
const shapeData = new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json');
</script>
<template>
    <ejs-maps>
        <e-layers>
            <e-layer :shapeData='shapeData'></e-layer>
        </e-layers>
    </ejs-maps>
</template>

<script>
  import { MapsComponent, LayersDirective, LayerDirective, MapAjax } from '@syncfusion/ej2-vue-maps';
  // Component registration
  export default {
    name: "App",
    // Declaring component and its directives
    components: {
        'ejs-maps' : MapsComponent,
        'e-layers' : LayersDirective,
        'e-layer' : LayerDirective
    },
    // Bound properties declarations
    data() {
      return {
        shapeData: new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json'),
      };
    }
  };
</script>

Run the Project

To run the project, use either npm or Yarn:

npm

npm run dev

yarn

yarn run dev

The application will display a basic Maps component using world map shape data:

vue-3-js-maps

Sample: You can explore the complete sample project in the vue3-maps-getting-started repository.

See Also