longdomap-react

Easy-to-use and lightweight React components for Longdo Map, providing a simple way to integrate Longdo Map into your React applications.

Table of Contents

• Features
• Installation
• Quick Start
• Components API
  • LongdoMap
  • Marker
  • Popup
  • Geometry
  • Layer
  • LongdoTag
• Map Instance API
  • Overlays
  • Event
  • Layers
  • Tags
  • UI Controls
• Utilities
  • Overlay Creators
  • Layer Creators
• Contributing
• License

Features

• Declarative Components: Use React components like LongdoMap, Marker, and Popup directly in your JSX.
• Full TypeScript Support: Written in TypeScript for a better development experience.
• Lightweight: Optimized for performance with a small bundle size.
• Customizable: Easily customize map options, markers, and other map objects.

Installation

Install the package using your favorite package manager:

npm install longdomap-react
# or
yarn add longdomap-react
# or
pnpm add longdomap-react

Quick Start

Here's a basic example of how to use longdomap-react:

import React from 'react';
import { LongdoMap, Marker, Map } from 'longdomap-react';

function App() {
  return (
    <div style={{ height: '500px' }}>
      <LongdoMap
        apiKey={"YOUR_LONGDO_MAP_API_KEY"}
        location={{ lon: 100.5018, lat: 13.7563 }}
        mapObj={(map: Map) => {
               map.language("en")
          }}
        zoom={10}
      >
        <Marker position={{ lon: 100.5018, lat: 13.7563 }} />
      </LongdoMap>
      
    </div>
  );
}

export default App;

Important: You need to get an API Key from the Longdo Map API website.

Components API

LongdoMap

The main map container component.

Prop	Type	Default	Description
apiKey	string	Required	The API key for Longdo Map service.
mapObj	(map: any) => void	-	Callback that receives the Longdo map object once it is ready.
location	{ lon: number; lat: number; }	{ lon: 100.529248, lat: 13.672898 }	Initial map location (Bangkok).
zoom	number	10	Initial map zoom level.
baseMap	string	"NORMAL"	The base map to use. See Longdo Docs for available layers.
height	string | number	400	Height of the map container.
width	string | number	"100%"	Width of the map container.
className	string	""	Optional CSS class for the container.
children	ReactNode	-	Child components like Marker, Popup, Geometry, etc.

Marker

Creates a marker on the map.

Prop	Type	Default	Description
position	{ lon: number, lat: number }	Required	The position of the marker.
title	string	-	The title of the marker (shows on hover).
detail	string	-	The detail text shown in the popup on click.
icon	{ url: string; offset?: { x: number; y: number }; }	-	Custom marker icon.
visibleRange	{ min: number; max: number }	-	The zoom level range where the marker is visible.
draggable	boolean	false	Allows the marker to be dragged by the user.

Popup

Creates a popup on the map.

Prop	Type	Default	Description
position	{ lon: number, lat: number }	Required	The position of the popup.
title	string	'Popup'	The title displayed at the top of the popup.
detail	string	'This is a popup'	Additional information displayed in the popup.
html	string	-	Custom HTML content to display inside the popup.
closable	boolean	true	If true, the popup will have a close button.
size	{ width: number; height: number }	{ width: 200, height: 100 }	The size of the popup.

Geometry

Creates various geometric shapes on the map.

Prop	Type	Default	Description
type	'polyline' | 'polygon' | 'circle' | 'donut' | 'rectangle'	Required	The type of geometry to render.
points	({ lon: number; lat: number } | null)[]	Required	An array of coordinate objects for the geometry's vertices.
radius	number	-	The radius of the geometry, used for the "circle" type.
options	object	-	Additional options for customizing appearance (e.g., lineColor, lineWidth, fillColor, title).

Layer

Adds a predefined layer to the map.

Prop	Type	Default	Description
layerName	string	Required	The name of the layer to add. See Longdo Docs for available layers.

LongdoTag

Adds a tag overlay to the map, showing points of interest.

Prop	Type	Default	Description
tagName	string	Required	The tag to apply to the map (e.g., "hotel"). See Tag List.

Map Instance API

You can get the map instance using the mapObj prop on the <LongdoMap> component. This object provides access to the full Longdo Map API.

Overlays

Manage elements on the map. Accessed via map.Overlays.

• add(overlay: any): Adds an overlay (marker, geometry, etc.).
• remove(overlay: any): Removes a specific overlay.
• clear(): Removes all overlays.
• list(): Returns an array of all overlays on the map.

Event

Bind callbacks to map events. Accessed via map.Event.

• bind(eventName: string, callback: (event: any) => void): Binds a function to a map event.
  • Common Events: click, doubleClick, drag, drop, zoom, ready, overlayClick. See EventName enum in src/interface/Event.ts for a full list.

Layers

Manage map layers. Accessed via map.Layers.

• setBase(layer: object): Sets the base map layer.
• add(layer: object): Adds an additional layer.
• remove(layer: object): Removes a layer.
• clear(): Clears all additional layers.

Tags

Manage POI tags. Accessed via map.Tags.

• add(tagName: string): Adds a tag layer.
• remove(tagName: string): Removes a tag layer.

UI Controls

Control the visibility of map UI elements. Accessed via map.Ui.

• DPad.visible(boolean)
• Zoombar.visible(boolean)
• Geolocation.visible(boolean)
• Toolbar.visible(boolean)
• LayerSelector.visible(boolean)
• Scale.visible(boolean)

Utilities

The library exports several utility functions to create Longdo Map objects programmatically.

Overlay Creators

These functions create overlay objects that can be added to the map using map.Overlays.add().

• createLongdoMarker(position, options)
• createPopup(position, options)
• createPolygon(points, options)
• createPolyline(points, options)
• createCircle(center, radius, options)
• createRectangle(bounds, options)
• createDot(position, options)

Layer Creators

Use these functions to create layer objects for use with map.Layers.add() or map.Layers.setBase().

• longdoLayer(layerName: string): Gets a predefined Longdo layer (e.g., NORMAL, POLITICAL).
• createWMSLayer(layerName, options)
• createWMTSLayer(layerName, options)
• createTMSLayer(layerName, options)

TMS Layer Example:

// The system automatically formats the URL to the correct tile format (e.g., /z/x/y.png)
const tmsLayer = createTMSLayer('', {
  url: 'https://mytileserver.com/tiles'
});
map?.Layers.add(tmsLayer);

Contributing

Contributions are welcome! Please see the Contributing Guidelines for more details.

License

This project is licensed under the MIT License - see the LICENSE file for details.