Syncfusion AI Assistant

How can I help you?

Getting Started with the Vue Maps Component in Vue 3

18 Mar 202618 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>) - Modern, function-based approach for better code reusable and organization of related logic. Ideal for complex components and advanced use cases.
  • 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

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 create vite@latest

or

yarn create vite

Follow the interactive prompts to complete the setup:

  1. Project name - Enter my-project (or your preferred name):
? Project name: » my-project
  1. Framework selection - Select Vue:
? Select a framework: » - Use arrow-keys. Return to submit.
Vanilla
> Vue
  React
  Preact
  Lit
  Svelte
  Others
  1. Variant selection - Choose JavaScript:
? Select a variant: » - Use arrow-keys. Return to submit.
> JavaScript
  TypeScript
  Customize with create-vue ↗
  Nuxt ↗
  1. Install dependencies - Navigate to the project directory and install dependencies:
cd my-project
npm install

or

cd my-project
yarn install

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 the following command:

npm install @syncfusion/ej2-vue-maps --save

or

yarn add @syncfusion/ej2-vue-maps

Add Syncfusion® Vue component

  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: Add the setup attribute to the <script> tag and use Maps.Inject() for module injection
    • Options API: Use standard component registration with a provide option for module injection
<script setup>
  import { MapsComponent as EjsMaps, LayersDirective as ELayers, LayerDirective as ELayer, MapAjax , Legend , DataLabel , MapsTooltip } from '@syncfusion/ej2-vue-maps';
  import { Maps } from '@syncfusion/ej2-maps';
  Maps.Inject(Legend, DataLabel, MapsTooltip);
</script>
<script>
import { MapsComponent, LayersDirective, LayerDirective, MapAjax, Legend, MapAjax, DataLabel, MapsTooltip } from '@syncfusion/ej2-vue-maps'
//Component registration
export default {
  name: "App",
  components: {
    'ejs-maps' : MapsComponent,
    'e-layers' : LayersDirective,
    'e-layer' : LayerDirective
  }
}
</script>
  1. Define the Maps component template with layer, title, legend, and other property bindings:
<template>
   <ejs-maps :titleSettings='titleSettings' :legendSettings='legendSettings'>
        <e-layers>
            <e-layer :shapeData='shapeData' :shapePropertyPath='shapePropertyPath' :shapeDataPath='shapeDataPath' :dataSource='dataSource' :shapeSettings='shapeSettings' :dataLabelSettings='dataLabelSettings' :tooltipSettings='tooltipSettings'></e-layer>
        </e-layers>
    </ejs-maps>
</template>
  1. Declare the property values referenced in the template:
<script setup>
    const titleSettings =  {
        text: 'UN security council countries'
    };
    const shapeData = new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json');
    const dataSource =  [{  "Country": "China", "Membership": "Permanent"},
            {"Country": "France","Membership": "Permanent" },
            { "Country": "Russia","Membership": "Permanent"},
            {"Country": "Kazakhstan","Membership": "Non-Permanent"},
            { "Country": "Poland","Membership": "Non-Permanent"},
            {"Country": "Sweden","Membership": "Non-Permanent"}];
    const shapePropertyPath = 'name';
    const shapeDataPath = 'Country';
    const shapeSettings = {
            colorValuePath: 'Membership',
            colorMapping: [
                {
                    value: 'Permanent', color: '#D84444'
                },
                {
                    value: 'Non-Permanent', color: '#316DB5'
                }
            ]
    };
    const dataLabelSettings = {
            visible: true,
            labelPath: 'name',
            smartLabelMode: 'Trim'
    };
    const legendSettings = {
        visible: true
    };
    const tooltipSettings = {
        visible: true,
        valuePath: 'Country'
    };
</script>
<script>
data() {
  return {
    titleSettings: {
        text: 'UN security council countries'
    },
    shapeData: new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json'),
    dataSource: [{  "Country": "China", "Membership": "Permanent"},
            {"Country": "France","Membership": "Permanent" },
            { "Country": "Russia","Membership": "Permanent"},
            {"Country": "Kazakhstan","Membership": "Non-Permanent"},
            { "Country": "Poland","Membership": "Non-Permanent"},
            {"Country": "Sweden","Membership": "Non-Permanent"}],
    shapePropertyPath: 'name',
    shapeDataPath: 'Country',
    shapeSettings: {
            colorValuePath: 'Membership',
            colorMapping: [
                {
                    value: 'Permanent', color: '#D84444'
                },
                {
                    value: 'Non-Permanent', color: '#316DB5'
                }
            ]
    },
    dataLabelSettings: {
            visible: true,
            labelPath: 'name',
            smartLabelMode: 'Trim'
    },
    legendSettings: {
        visible: true
    },
    tooltipSettings: {
        visible: true,
        valuePath: 'Country'
    }
  };
}
</script>

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

<template>
    <ejs-maps :titleSettings='titleSettings' :legendSettings='legendSettings'>
        <e-layers>
            <e-layer :shapeData='shapeData' :shapePropertyPath='shapePropertyPath' :shapeDataPath='shapeDataPath' :dataSource='dataSource' :shapeSettings='shapeSettings' :dataLabelSettings='dataLabelSettings' :tooltipSettings='tooltipSettings'></e-layer>
        </e-layers>
    </ejs-maps>
</template>

<script setup>
import { MapsComponent as EjsMaps, LayersDirective as ELayers, LayerDirective as ELayer, MapAjax , Legend , DataLabel , MapsTooltip } from '@syncfusion/ej2-vue-maps';
import { Maps } from '@syncfusion/ej2-maps';
Maps.Inject(Legend, DataLabel, MapsTooltip);
    const titleSettings =  {
        text: 'UN security council countries'
    };
    const shapeData = new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json');
    const dataSource =  [{  "Country": "China", "Membership": "Permanent"},
            {"Country": "France","Membership": "Permanent" },
            { "Country": "Russia","Membership": "Permanent"},
            {"Country": "Kazakhstan","Membership": "Non-Permanent"},
            { "Country": "Poland","Membership": "Non-Permanent"},
            {"Country": "Sweden","Membership": "Non-Permanent"}];
    const shapePropertyPath = 'name';
    const shapeDataPath = 'Country';
    const shapeSettings = {
            colorValuePath: 'Membership',
            colorMapping: [
                {
                    value: 'Permanent', color: '#D84444'
                },
                {
                    value: 'Non-Permanent', color: '#316DB5'
                }
            ]
    };
    const dataLabelSettings = {
            visible: true,
            labelPath: 'name',
            smartLabelMode: 'Trim'
    };
    const legendSettings = {
        visible: true
    };
    const tooltipSettings = {
        visible: true,
        valuePath: 'Country'
    };
</script>
<template>
    <ejs-maps :titleSettings='titleSettings' :legendSettings='legendSettings'>
        <e-layers>
            <e-layer :shapeData='shapeData' :shapePropertyPath='shapePropertyPath' :shapeDataPath='shapeDataPath' :dataSource='dataSource' :shapeSettings='shapeSettings' :dataLabelSettings='dataLabelSettings' :tooltipSettings='tooltipSettings'></e-layer>
        </e-layers>
    </ejs-maps>
</template>

<script>
  import { MapsComponent, LayersDirective, LayerDirective, MapAjax, Legend, DataLabel, MapsTooltip } 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 {
        titleSettings: {
           text: 'UN security council countries'
        },
        shapeData: new MapAjax('https://cdn.syncfusion.com/maps/map-data/world-map.json'),
        dataSource: [{  "Country": "China", "Membership": "Permanent"},
                {"Country": "France","Membership": "Permanent" },
                { "Country": "Russia","Membership": "Permanent"},
                {"Country": "Kazakhstan","Membership": "Non-Permanent"},
                { "Country": "Poland","Membership": "Non-Permanent"},
                {"Country": "Sweden","Membership": "Non-Permanent"}],
        shapePropertyPath: 'name',
        shapeDataPath: 'Country',
        shapeSettings: {
                colorValuePath: 'Membership',
                colorMapping: [
                    {
                        value: 'Permanent', color: '#D84444'
                    },
                    {
                        value: 'Non-Permanent', color: '#316DB5'
                    }
                ]
        },
        dataLabelSettings: {
                visible: true,
                labelPath: 'name',
                smartLabelMode: 'Trim'
        },
        legendSettings: {
            visible: true
        },
        tooltipSettings: {
            visible: true,
            valuePath: 'Country'
        }
      };
    },
    provide: {
      maps:[Legend, DataLabel, MapsTooltip]
    }
  };
</script>

Run the project

Execute the following command to start the development server:

npm run dev

or

yarn run dev

The application will display a Maps component showing UN Security Council countries with color-coded memberships:

vue-3-js-maps

Sample: vue3-maps-getting-started.

See also