---
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 |
| `latitude` | `number` | No | `39.909652` | Center latitude |
| `scale` | `number` | No | `16` | Zoom level, range 3–20 |
| `min-scale` | `number` | No | `4` | Minimum zoom level |
| `max-scale` | `number` | No | `19` | Maximum zoom level |
| `markers` | `any[]` | No | `[]` | Marker |
| `polyline` | `any[]` | No | `[]` | Polyline |
| `circles` | `any[]` | No | `[]` | Circular area |
| `polygons` | `any[]` | No | `[]` | Polygonal area |
| `disable-rotate` | `boolean` | No | `false` | Disable rotation |
| `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}}"
  min-scale="{{10}}"
  max-scale="{{18}}"
  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).