---
name: "map"
mode: "component"
versionRequirements:
  - { name: "Base Library", version: "2.10.0" }
title: "map - Map"
---

## map

> [VERSION] Base Library >= 2.10.0

### Description

Map component.

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `longitude` | `number` | No | `116.404177` | Center longitude. On HarmonyOS, takes effect only at initialization; dynamic updates are ignored. |
| `latitude` | `number` | No | `39.909652` | Center latitude. On HarmonyOS, takes effect only at initialization; dynamic updates are ignored. |
| `scale` | `number` | No | `16` | Zoom level, range 4–19. On HarmonyOS, takes effect only at initialization; dynamic updates are ignored. |
| `markers` | `any[]` | No | `[]` | Marker. Not supported on HarmonyOS |
| `polyline` | `any[]` | No | `[]` | Route. Not supported on HarmonyOS |
| `circles` | `any[]` | No | `[]` | Circular area. Not supported on HarmonyOS |
| `polygons` | `any[]` | No | `[]` | Polygon area. Not supported on HarmonyOS |
| `disable-animation` | `boolean` | No | `false` | Disable built-in map animations. Supported on iOS only, and only applies when moving the center point. |
| `disable-rotate` | `boolean` | No | `false` | Disable rotation gestures. Not supported on HarmonyOS. |
| `map-type` | `number` | No | - | Map type: -1 follows the App theme, 0 dark, 1 light, 2 satellite map. Not supported on HarmonyOS |
| `show-scale-view` | `boolean` | No | `false` | Whether to show the scale control. Supported on Android only, and only at initialization. |
| `background-color` | `string` | No | `"#ffffff"` | Background color; must be in hex |
| `border-width` | `number` | No | `0` | Border width, in px |
| `border-style` | `string` | No | `"solid"` | Border style. Options: solid (solid line), dashed (dashed line) |
| `border-color` | `string` | No | `"#ffffff"` | Border color, must be in hexadecimal format |
| `border-radius` | `number` | No | `0` | Border radius, in px |
| `border-radius-top-left` | `number` | No | - | Top-left corner radius, in px |
| `border-radius-top-right` | `number` | No | - | Top-right corner radius, in px |
| `border-radius-bottom-left` | `number` | No | - | Bottom-left corner radius, in px |
| `border-radius-bottom-right` | `number` | No | - | Bottom-right corner radius, in px |

#### Events

| Event | Type | Description |
| --- | --- | --- |
| `markertap` | `(event: MapMarkertapEvent) => void` | Triggered when a marker is clicked |
| `callouttap` | `(event: MapCallouttapEvent) => void` | Triggered when the marker's callout is clicked |
| `regionchange` | `(event: MapRegionchangeEvent) => void` | Triggered when the viewport changes |
| `tap` | `(event: Object) => void` | Fires when the map is clicked |
| `updated` | `(event: Object) => void` | Fires when the map render update completes |

**MapMarkertapEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"markertap"` |  |
| `detail` | `MapMarkertapDetail` |  |

**MapCallouttapEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"callouttap"` |  |
| `detail` | `MapCallouttapDetail` |  |

**MapRegionchangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"regionchange"` |  |
| `detail` | `MapRegionchangeDetail` |  |

**tap callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"tap"` |  |

**updated callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"updated"` |  |

### Examples

#### Markers and callouts

*index.tyml*

```xml
<map
  longitude="{{lng}}"
  latitude="{{lat}}"
  scale="{{14}}"
  markers="{{markers}}"
  class="map"
  bind:markertap="onMarkerTap"
  bind:callouttap="onCalloutTap"
/>
```

*index.tyss*

```css
.map {
  width: 100%;
  height: 500rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    lng: 116.397428,
    lat: 39.90923,
    markers: [
      {
        id: 1,
        longitude: 116.397428,
        latitude: 39.90923,
        title: 'Tiananmen',
        iconPath: '/images/marker.png',
        width: 30,
        height: 30,
        callout: {
          content: 'Tiananmen Square',
          color: '#333',
          fontSize: 14,
          bgColor: '#fff',
          borderRadius: 4,
          padding: 8,
          textAlign: 'center',
        },
      },
      {
        id: 2,
        longitude: 116.407428,
        latitude: 39.91523,
        title: 'Forbidden City',
        iconPath: '/images/marker.png',
        width: 30,
        height: 30,
      },
    ],
  },
  onMarkerTap(e) {
    console.log('Marker tapped:', e.detail.markerId);
  },
  onCalloutTap(e) {
    console.log('Callout tapped:', e.detail.markerId);
  },
});
```

#### Routes and overlays

*index.tyml*

```xml
<map
  longitude="{{lng}}"
  latitude="{{lat}}"
  scale="{{13}}"
  polyline="{{polyline}}"
  circles="{{circles}}"
  polygons="{{polygons}}"
  class="map"
  bind:regionchange="onRegionChange"
/>
```

*index.tyss*

```css
.map {
  width: 100%;
  height: 500rpx;
  border-radius: 12px;
}
```

*index.js*

```javascript
Page({
  data: {
    lng: 116.407428,
    lat: 39.91523,
    polyline: [
      {
        points: [
          { latitude: 39.90923, longitude: 116.397428 },
          { latitude: 39.91523, longitude: 116.407428 },
          { latitude: 39.92023, longitude: 116.417428 },
        ],
        color: '#1890ff',
        width: 4,
        dottedLine: false,
      },
    ],
    circles: [
      {
        latitude: 39.90923,
        longitude: 116.397428,
        radius: 500,
        color: '#1890ff80',
        fillColor: '#1890ff20',
        strokeWidth: 2,
      },
    ],
    polygons: [
      {
        points: [
          { latitude: 39.91, longitude: 116.40 },
          { latitude: 39.92, longitude: 116.41 },
          { latitude: 39.91, longitude: 116.42 },
        ],
        strokeColor: '#ff4d4f',
        fillColor: '#ff4d4f20',
        strokeWidth: 2,
      },
    ],
  },
  onRegionChange(e) {
    console.log('Region change:', e.detail.type);
  },
});
```


> The WebView emulation on Tuya MiniApp IDE differs from real devices. The real device behavior prevails. Real devices use Amap in China and Google Maps overseas.

<DemoBlock 
  githubUrl="https://github.com/Tuya-Community/tuya-miniapp-demo/tree/master/rayMap" 
  qrCodeUrl="/images/qrCode/rayMap.png" 
  lang="en">
</DemoBlock>


### Related Documents

- Related API: [ty.createMapContext](/en/miniapp/develop/miniapp/api/media/map/createMapContext)
- This is a native component rendered based on heterolayers. Take care of the [limitations of the native component](/en/miniapp/develop/miniapp/component/native-component/native-component).

### FAQ

1. The longitude and latitude are required properties for the map component. If left empty, the coordinates of Beijing are used by default.
2. The WebView emulation on Tuya MiniApp IDE differs from real devices. The real device behavior prevails.
3. For more information about principles, see [Native component rendered based on heterolayers](/en/miniapp/develop/miniapp/component/native-component/native-component).
4. Take care of the [limitations of the native component](/en/miniapp/develop/miniapp/component/native-component/native-component).