---
name: "Map"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.6.9" }
  - { name: "Base library", version: "2.0.12" }
  - { name: "MapKit", version: "2.2.2" }
title: "Map - Map"
---

## Map

> [VERSION] @ray-js/ray >= 0.6.9 | Base library >= 2.0.12 | MapKit >= 2.2.2

### Description

Map component: On real devices in mainland China, it uses AMap; overseas, it uses Google Maps. In Tuya MiniApp IDE and the online preview, it is simulated via WebView and may differ from real devices. Use real-device behavior as the reference.

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `longitude` | `number` | No | - | Center longitude. On HarmonyOS, only takes effect at initialization; runtime updates are ignored. |
| `latitude` | `number` | No | - | Center latitude. On HarmonyOS, only takes effect at initialization; runtime updates are ignored. |
| `scale` | `number` | No | `16` | Zoom level, range 4-19. On HarmonyOS, only takes effect at initialization; runtime updates are ignored. |
| `disableAnimation` | `boolean` | No | - | Disable built-in map animations. Supported on iOS only, and only effective when the center moves. |
| `disableRotate` | `boolean` | No | - | Disable rotation gestures. Defaults to false. Not supported on HarmonyOS. |
| `mapType` | `number` | No | - | Map type: -1 follow app theme, 0 dark, 1 light, 2 satellite. Not supported on HarmonyOS. |
| `markers` | `MapMarker[]` | No | - | Markers. Not supported on HarmonyOS. |
| `polyline` | `MapPolyline[]` | No | - | Routes. Not supported on HarmonyOS. |
| `circles` | `MapCircle[]` | No | - | Circles. Not supported on HarmonyOS. |
| `polygons` | `MapPolygon[]` | No | - | Polygons. Not supported on HarmonyOS. |
| `borderWidth` | `number` | No | `0` | Border width, in px |
| `borderStyle` | `"solid" \| "dashed"` | No | `"solid"` | Border style |
| `borderColor` | `string` | No | `"#ffffff"` | Border color, must be hex format |
| `borderRadius` | `number` | No | `0` | Border radius, in px |
| `borderRadiusTopLeft` | `number` | No | - | Top-left border radius, in px |
| `borderRadiusTopRight` | `number` | No | - | Top-right border radius, in px |
| `borderRadiusBottomLeft` | `number` | No | - | Bottom-left border radius, in px |
| `borderRadiusBottomRight` | `number` | No | - | Bottom-right border radius, in px |
| `backgroundColor` | `string` | No | `"#ffffff"` | Background color, must be hex format |
| `onMarkertap` | `(event: MapMarkertapEvent) => void` | No | - | Triggered when a marker is tapped |
| `onCallouttap` | `(event: MapCallouttapEvent) => void` | No | - | Triggered when the marker’s callout is tapped |
| `onRegionchange` | `(event: MapRegionchangeEvent) => void` | No | - | Triggered when the viewport changes |
| `updateLayout` | `unknown` | No | - | Used for cross-layer components to notify the container layer to update styles |

### Referenced Types

##### `interface` MapMarker

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `number` | No | Marker ID |
| `longitude` | `number` | Yes | Longitude |
| `latitude` | `number` | Yes | Latitude |
| `title` | `string` | No | Marker name |
| `styleId` | `string` | No | Callout style type ID |
| `callout` | `MapCallout` | No | Callout above the marker |
| `iconPath` | `string` | No | Icon path |
| `rotate` | `number` | No | Rotation angle |
| `width` | `number \| string` | No | Marker icon width |
| `height` | `number \| string` | No | Marker icon height |

##### `interface` MapPolyline

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `points` | `MapPoint[]` | Yes | Latitude/longitude array |
| `color` | `string` | No | Line color (hex) |
| `width` | `number` | No | Line width |
| `dottedLine` | `boolean` | No | Whether dashed |

##### `interface` MapCircle

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `latitude` | `number` | Yes | Latitude |
| `longitude` | `number` | Yes | Longitude |
| `color` | `string` | No | Stroke color (hex) |
| `fillColor` | `string` | No | Fill color (hex) |
| `radius` | `number` | Yes | Radius |
| `strokeWidth` | `number` | No | Stroke width |

##### `interface` MapPolygon

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `points` | `MapPoint[]` | Yes | Latitude/longitude array |
| `strokeColor` | `string` | No | Stroke color |
| `fillColor` | `string` | No | Fill color |
| `strokeWidth` | `number` | No | Stroke width |

##### `interface` MapMarkertapEvent

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | `MapMarkerIdDetail` | Yes | Event detail data |

##### `interface` MapCallouttapEvent

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | `MapMarkerIdDetail` | Yes | Event detail data |

##### `interface` MapRegionchangeEvent

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | `MapRegionChangeDetail` | Yes | Event detail data |

##### `interface` MapCallout

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | `string` | No | Text |
| `color` | `string` | No | Text color |
| `fontSize` | `number` | No | Font size |
| `borderRadius` | `number` | No | Border radius |
| `borderWidth` | `number` | No | Border width |
| `borderColor` | `string` | No | Border color |
| `bgColor` | `string` | No | Background color |
| `padding` | `number` | No | Text padding |
| `textAlign` | `"left" \| "right" \| "center"` | No | Text alignment |
| `anchorX` | `number` | No | Horizontal offset; positive to the right |
| `anchorY` | `number` | No | Vertical offset; positive downward |

##### `interface` MapMarkerIdDetail

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `markerId` | `number` | Yes | Marker ID |

##### `interface` MapRegionChangeDetail

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"begin" \| "end"` | Yes | Change type |
| `causedBy` | `string` | Yes | Causes of viewport changes |

##### `type` MapPoint

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `latitude` | `number` | Yes | Latitude |
| `longitude` | `number` | Yes | Longitude |


### Examples

#### Basic usage

```tsx
import React from 'react';
import { Map, View } from '@ray-js/ray';
export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Map
        longitude={116.397428}
        latitude={39.90923}
        scale={16}
        style={{ width: '100%', height: '300px' }}
      />
    </View>
  );
}
```

#### Markers and callouts

```tsx
import React from 'react';
import { Map, View, Text } from '@ray-js/ray';

export default function () {
  const 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,
    },
  ];

  return (
    <View style={{ padding: '20px' }}>
      <Map
        longitude={116.397428}
        latitude={39.90923}
        scale={14}
        minScale={10}
        maxScale={18}
        markers={markers}
        style={{ width: '100%', height: '300px' }}
        onMarkertap={(e) => console.log('Marker:', e.detail.markerId)}
        onCallouttap={(e) => console.log('Callout:', e.detail.markerId)}
        onInitdone={() => console.log('Map initialized')}
      />
    </View>
  );
}
```

#### Routes and overlays

```tsx
import React from 'react';
import { Map, View } from '@ray-js/ray';

export default function () {
  const 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,
    },
  ];

  const circles = [
    {
      latitude: 39.90923,
      longitude: 116.397428,
      radius: 500,
      color: '#1890ff80',
      fillColor: '#1890ff20',
      strokeWidth: 2,
    },
  ];

  const 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,
    },
  ];

  return (
    <View style={{ padding: '20px' }}>
      <Map
        longitude={116.407428}
        latitude={39.91523}
        scale={13}
        polyline={polyline}
        circles={circles}
        polygons={polygons}
        borderRadius={12}
        style={{ width: '100%', height: '300px' }}
        onRegionchange={(e) => console.log('Region change:', e.detail.type)}
      />
    </View>
  );
}
```


### Related Links

Related API: [createMapContext](/en/miniapp/develop/miniapp/api/media/map/createMapContext). This is a native component based on off-screen rendering. Please note the [native component usage restrictions](/en/miniapp/develop/miniapp/component/native-component/native-component).

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

### FAQ

1. The latitude and longitude of the map component are required. If not provided, Beijing's coordinates are used as default values.
2. The Tuya MiniApp IDE simulates the map via WebView, which differs from behavior on a real device. Please use the real device result as the reference.
3. For related principles, refer to [Native components based on off-screen rendering](/en/miniapp/develop/miniapp/component/native-component/native-component).
4. Please note the [native component usage restrictions](/en/miniapp/develop/miniapp/component/native-component/native-component).