JavaScript/jQuery Map Options

Default Value: { bing: '', google: '', googleStatic: '' }

If you have more than one map provider in your application, specify the keys in the object fields as shown below. Otherwise, you can assign the key directly to the apiKey property.

jQuery

index.js

$(function() {
    $("#mapContainer").dxMap({
        // ...
        apiKey: {
            bing: "MY_BING_MAPS_KEY",
            google: "MY_GOOGLE_MAPS_KEY",
            googleStatic: "MY_GOOGLE_STATIC_MAPS_KEY"
        }
    });
});

Angular

app.component.html

app.component.ts

app.module.ts

<dx-map ... >
    <dxo-api-key
        bing="MY_BING_MAPS_KEY"
        google="MY_GOOGLE_MAPS_KEY"
        googleStatic="MY_GOOGLE_STATIC_MAPS_KEY">
    </dxo-api-key>
</dx-map>

import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent { }

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';

import { DxMapModule } from 'devextreme-angular';

@NgModule({
    declarations: [
        AppComponent
    ],
    imports: [
        BrowserModule,
        DxMapModule
    ],
    providers: [ ],
    bootstrap: [AppComponent]
})
export class AppModule { }

Vue

App.vue

<template>
    <DxMap ... >
        <DxApiKey
            bing="MY_BING_MAPS_KEY"
            google="MY_GOOGLE_MAPS_KEY"
            googleStatic="MY_GOOGLE_STATIC_MAPS_KEY"
        />
    </DxMap>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import DxMap, {
    DxApiKey
} from 'devextreme-vue/map';

export default {
    components: {
        DxMap,
        DxApiKey
    }
}
</script>

React

App.js

import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import Map, {
    ApiKey
} from 'devextreme-react/map';

const App = () => {
    return (
        <Map ... >
            <ApiKey
                bing="MY_BING_MAPS_KEY"
                google="MY_GOOGLE_MAPS_KEY"
                googleStatic="MY_GOOGLE_STATIC_MAPS_KEY"
            />
        </Map>
    );
}
export default App;

NOTE

The value of this property cannot be changed dynamically.

autoAdjust

Specifies whether the UI component automatically adjusts center and zoom property values when adding a new marker or route, or if a new UI component contains markers or routes by default.

Type:

Default Value: true

If autoAdjust is enabled, zoom is set to the maximum value allowing all markers and routes to be displayed at the same time. The center is changed so that markers and routes are aligned with the UI component's center. Set the autoAdjust property to false to disable this behavior.

Note that the zoom level can only be automatically decreased to display all markers and routes. If the current zoom level allows all routes and markers to be displayed on the map, it remains unchanged.

center

An object, a string, or an array specifying which part of the map is displayed at the UI component's center using coordinates. The UI component can change this value if autoAdjust is enabled.

Type:

Array<Number>

Raised Events: onOptionChanged

You can specify the center value in one of the following formats:

{ lat: 40.749825, lng: -73.987963}
"40.749825, -73.987963"
[40.749825, -73.987963]
"Brooklyn Bridge,New York,NY"

controls

Specifies whether or not map UI component controls are available.

Type:

Default Value: false

Assign a Boolean value to this property to enable or disable all controls at once - both the map navigation control and the map type control.

disabled

Specifies whether the UI component responds to user interaction.

Type:

Default Value: false

elementAttr

Specifies the global attributes to be attached to the UI component's container element.

Type:

Default Value: {}

jQuery

$(function(){
    $("#mapContainer").dxMap({
        // ...
        elementAttr: {
            id: "elementId",
            class: "class-name"
        }
    });
});

Angular

HTML

TypeScript

<dx-map ...
    [elementAttr]="{ id: 'elementId', class: 'class-name' }">
</dx-map>

import { DxMapModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxMapModule
    ],
    // ...
})

Vue

App.vue

<template>
    <DxMap ...
        :element-attr="mapAttributes">
    </DxMap>
</template>

<script>
import DxMap from 'devextreme-vue/map';

export default {
    components: {
        DxMap
    },
    data() {
        return {
            mapAttributes: {
                id: 'elementId',
                class: 'class-name'
            }
        }
    }
}
</script>

React

App.js

import React from 'react';

import Map from 'devextreme-react/map';

class App extends React.Component {
    mapAttributes = {
        id: 'elementId',
        class: 'class-name'
    }

    render() {
        return (
            <Map ...
                elementAttr={this.mapAttributes}>
            </Map>
        );
    }
}
export default App;

focusStateEnabled

Specifies whether the UI component can be focused using keyboard navigation.

Type:

Default Value: true (desktop)

height

Specifies the UI component's height.

Type:

Return Value:

The UI component's height.

Default Value: 300

This property accepts a value of one of the following types:

Number
The height in pixels.
String
A CSS-accepted measurement of height. For example, "55px", "20vh", "80%", "inherit".
Function (deprecated since v21.2)
Refer to the W0017 warning description for information on how you can migrate to viewport units.

hint

Specifies text for a hint that appears when a user pauses on the UI component.

Type:

Default Value: undefined

hoverStateEnabled

Specifies whether the UI component changes its state when a user pauses on it.

Type:

Default Value: false

markerIconSrc

A URL pointing to the custom icon to be used for map markers.

Type:

To set a custom icon for an individual marker, specify the iconSrc field of the corresponding marker data source object.

markers[]

An array of markers displayed on a map.

Type:

Array<Object>

Raised Events: onMarkerAdded onMarkerRemoved

If you use the Knockout approach when working with the Map UI component, you can pass an observable array to the markers property to easily manage markers.

View on GitHub

onClick

A function that is executed when any location on the map is clicked or tapped.

Type:

Function parameters:

ClickEvent

Information about the event.

Object structure:

Name

Type

Description

component

The UI component's instance.

element

The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.

event

Event (jQuery or EventObject)

The event that caused the function to execute. It is an EventObject or a jQuery.Event when you use jQuery.

Default Value: null

onDisposing

A function that is executed before the UI component is disposed of.

Type:

Function parameters:

DisposingEvent

Information about the event.

Object structure:

Name	Type	Description
element	HTMLElement \| jQuery	The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.
component	Map	The UI component's instance.

Name

Type

Description

element

The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.

component

The UI component's instance.

Default Value: null

onInitialized

A function used in JavaScript frameworks to save the UI component instance.

Type:

Function parameters:

InitializedEvent

Information about the event.

Object structure:

Name	Type	Description
element	HTMLElement \| jQuery	The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.
component	Map	The UI component's instance.

Name

Type

Description

element

The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.

component

The UI component's instance.

Default Value: null

Angular

app.component.html

app.component.ts

<dx-map ...
    (onInitialized)="saveInstance($event)">
</dx-map>

import { Component } from "@angular/core";
import Map from "devextreme/ui/data_grid";
// ...
export class AppComponent {
    mapInstance: Map;
    saveInstance (e) {
        this.mapInstance = e.component;
    }
}

Vue

App.vue (Options API)

App.vue (Composition API)

<template>
    <div>
        <DxMap ...
            @initialized="saveInstance">
        </DxMap>
    </div>
</template>

<script>
import DxMap from 'devextreme-vue/map';

export default {
    components: {
        DxMap
    },
    data: function() {
        return {
            mapInstance: null
        };
    },
    methods: {
        saveInstance: function(e) {
            this.mapInstance = e.component;
        }
    }
};
</script>

<template>
    <div>
        <DxMap ...
            @initialized="saveInstance">
        </DxMap>
    </div>
</template>

<script setup>
import DxMap from 'devextreme-vue/map';

let mapInstance = null;

const saveInstance = (e) => {
    mapInstance = e.component;
}
</script>

React

App.js

import Map from 'devextreme-react/map';

class App extends React.Component {
    constructor(props) {
        super(props);

        this.saveInstance = this.saveInstance.bind(this);
    }

    saveInstance(e) {
        this.mapInstance = e.component;
    }

    render() {
        return (
            <div>
                <Map onInitialized={this.saveInstance} />
            </div>
        );
    }
}

jQuery

Get a UI component Instance in jQuery

Angular

Get a UI component Instance in Angular

Vue

Get a UI component Instance in Vue

React

Get a UI component Instance in React

onMarkerAdded

A function that is executed when a marker is created on the map.

Type:

Function parameters:

MarkerAddedEvent

Information about the event.

Object structure:

Name	Type	Description
component	Map	The UI component's instance.
element	HTMLElement \| jQuery	The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.
options	Object	The added marker's data.
originalMarker	Object	The original marker that the current map provider uses (only for "google" and "bing" providers).

Default Value: null

onMarkerRemoved

A function that is executed when a marker is removed from the map.

Type:

Function parameters:

MarkerRemovedEvent

Information about the event.

Object structure:

Name

Type

Description

component

The UI component's instance.

element

The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.

options

The removed marker's data.

Default Value: null

onOptionChanged

A function that is executed after a UI component property is changed.

Type:

Function parameters:

OptionChangedEvent

Information about the event.

Object structure:

Name	Type	Description
value	any	The modified property's new value.
previousValue	any	The UI component's previous value.
name	String	The modified property if it belongs to the first level. Otherwise, the first-level property it is nested into.
fullName	String	The path to the modified property that includes all parent properties.
element	HTMLElement \| jQuery	The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.
component	Map	The UI component's instance.

Default Value: null

The following example shows how to subscribe to component property changes:

jQuery

index.js

$(function() {
    $("#mapContainer").dxMap({
        // ...
        onOptionChanged: function(e) {
            if(e.name === "changedProperty") {
                // handle the property change here
            }
        }
    });
});

Angular

app.component.html

app.component.ts

app.module.ts

<dx-map ...
    (onOptionChanged)="handlePropertyChange($event)"> 
</dx-map>

import { Component } from '@angular/core'; 

@Component({ 
    selector: 'app-root', 
    templateUrl: './app.component.html', 
    styleUrls: ['./app.component.css'] 
}) 

export class AppComponent { 
    // ...
    handlePropertyChange(e) {
        if(e.name === "changedProperty") { 
            // handle the property change here
        }
    }
}

import { BrowserModule } from '@angular/platform-browser'; 
import { NgModule } from '@angular/core'; 
import { AppComponent } from './app.component'; 
import { DxMapModule } from 'devextreme-angular'; 

@NgModule({ 
    declarations: [ 
        AppComponent 
    ], 
    imports: [ 
        BrowserModule, 
        DxMapModule 
    ], 
    providers: [ ], 
    bootstrap: [AppComponent] 
}) 

export class AppModule { }

Vue

App.vue

<template> 
    <DxMap ...
        @option-changed="handlePropertyChange"
    />            
</template> 

<script>  
import 'devextreme/dist/css/dx.light.css'; 
import DxMap from 'devextreme-vue/map'; 

export default { 
    components: { 
        DxMap
    }, 
    // ...
    methods: { 
        handlePropertyChange: function(e) {
            if(e.name === "changedProperty") {
                // handle the property change here
            }
        }
    } 
} 
</script>

React

App.js

import React from 'react';  
import 'devextreme/dist/css/dx.light.css'; 

import Map from 'devextreme-react/map'; 

const handlePropertyChange = (e) => {
    if(e.name === "changedProperty") {
        // handle the property change here
    }
}

export default function App() { 
    return ( 
        <Map ...
            onOptionChanged={handlePropertyChange}
        />        
    ); 
}

onReady

A function that is executed when the map is ready.

Type:

Function parameters:

ReadyEvent

Information about the event.

Object structure:

Name

Type

Description

component

The UI component's instance.

element

The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.

originalMap

View on GitHub View on GitHub

The current provider's map data.

Default Value: null

You can use component field to access properties that are common for all supported Map providers. To access provider-specific API, utilize the originalMap parameter. The examples below demonstrate this solution:

onRouteAdded

A function that is executed when a route is created on the map.

Type:

Function parameters:

RouteAddedEvent

Information about the event.

Object structure:

Name	Type	Description
component	Map	The UI component's instance.
element	HTMLElement \| jQuery	The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.
options	Object	The added route's data.
originalRoute	Object	The original route that the current map provider uses (only for "google" and "bing" providers).

Default Value: null

onRouteRemoved

A function that is executed when a route is removed from the map.

Type:

Function parameters:

RouteRemovedEvent

Information about the event.

Object structure:

Name

Type

Description

component

The UI component's instance.

element

The UI component's container. It is an HTML Element or a jQuery Element when you use jQuery.

options

The removed route's data.

Default Value: null

provider

The name of the current map data provider.

Type:

MapProvider

Default Value: 'google'

Use the "googleStatic" provider to connect route points directly rather than by following the street layout.

IMPORTANT

On May 21, 2024, Microsoft announced that Bing Maps for Enterprise and its API will be discontinued. Azure Maps will be a single unified enterprise mapping platform available from Microsoft.

We are working on API compatible with Azure Maps and expect to ship it with our next major release (v24.2). If you have an existing license to Bing Maps for Enterprise, you can continue using our existing API. You need to transition to new API until June 30, 2025 (free and basic license) or until June 30, 2028 (enterprise license).

The last date you can get a new license to Bing Maps for Enterprise is June 30, 2024. If you do not have an existing license after that date, you would not be able to use our map controls with Bing Maps or Azure Maps (until we release the new API). During that time, you can use other map providers supported by our controls, such as Google or GoogleStatic.

routes[]

An array of routes shown on the map.

Type:

Array<Object>

Raised Events: onRouteAdded onRouteRemoved

rtlEnabled

Switches the UI component to a right-to-left representation.

Type:

DataGrid Demo Navigation UI Demo Editors Demo

Default Value: false

When this property is set to true, the UI component text flows from right to left, and the layout of elements is reversed. To switch the entire application/site to the right-to-left representation, assign true to the rtlEnabled field of the object passed to the DevExpress.config(config) method.

JavaScript

DevExpress.config({
    rtlEnabled: true
});

tabIndex

Specifies the number of the element when the Tab key is used for navigating.

Type:

Number

Default Value: 0

The value of this property will be passed to the tabindex attribute of the HTML element that underlies the UI component.

type

The type of a map to display.

Type:

MapType

Default Value: 'roadmap'

visible

Specifies whether the UI component is visible.

Type: