0
# Pigeon Maps
1
2
Pigeon Maps is a performance-first React-centric extendable map engine that provides ReactJS maps without external dependencies. It offers zero external dependencies for basic mapping functionality, supporting essential features like tile display, arbitrary overlays and markers, drag and touch interactions, fractional zooming with smooth animations, event handling, and various zoom controls.
3
4
## Package Information
5
6
- **Package Name**: pigeon-maps
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript with React
9
- **Installation**: `npm install pigeon-maps`
10
11
## Core Imports
12
13
```typescript
14
import { Map, Marker, Overlay, ZoomControl } from "pigeon-maps";
15
```
16
17
For provider utilities:
18
19
```typescript
20
import { osm, stamenToner, maptiler } from "pigeon-maps/providers";
21
```
22
23
CommonJS:
24
25
```javascript
26
const { Map, Marker, Overlay, ZoomControl } = require("pigeon-maps");
27
const { osm, stamenToner, maptiler } = require("pigeon-maps/providers");
28
```
29
30
## Basic Usage
31
32
```tsx
33
import React from "react";
34
import { Map, Marker } from "pigeon-maps";
35
36
function MyMap() {
37
return (
38
<Map height={400} center={[50.879, 4.6997]} zoom={11}>
39
<Marker anchor={[50.879, 4.6997]} />
40
</Map>
41
);
42
}
43
```
44
45
## Architecture
46
47
Pigeon Maps is built around several key components:
48
49
- **Map Component**: Core interactive map with tile rendering, zoom/pan controls, and event handling
50
- **Overlay System**: Positioning system for markers, overlays, and interactive elements
51
- **Tile Providers**: Functions that generate tile URLs for different map services
52
- **Event System**: React-based event handling for clicks, drags, and gestures
53
- **Coordinate System**: Utilities for converting between lat/lng and pixel coordinates
54
- **Animation Engine**: Smooth transitions for zoom and pan operations
55
56
## Capabilities
57
58
### Core Map Display
59
60
The main Map component that renders interactive maps with tile layers, handles user interactions, and manages the map state.
61
62
```typescript { .api }
63
function Map(props: MapProps): JSX.Element;
64
65
interface MapProps {
66
// Position and size
67
center?: Point;
68
defaultCenter?: Point;
69
zoom?: number;
70
defaultZoom?: number;
71
width?: number;
72
height?: number;
73
defaultWidth?: number;
74
defaultHeight?: number;
75
76
// Map configuration
77
provider?: (x: number, y: number, z: number, dpr?: number) => string;
78
dprs?: number[];
79
minZoom?: number;
80
maxZoom?: number;
81
animate?: boolean;
82
animateMaxScreens?: number;
83
84
// Interaction settings
85
mouseEvents?: boolean;
86
touchEvents?: boolean;
87
metaWheelZoom?: boolean;
88
twoFingerDrag?: boolean;
89
zoomSnap?: boolean;
90
limitBounds?: 'center' | 'edge';
91
92
// Event handlers
93
onClick?: ({ event, latLng, pixel }: ClickEvent) => void;
94
onBoundsChanged?: ({ center, zoom, bounds, initial }: BoundsChangeEvent) => void;
95
onAnimationStart?: () => void;
96
onAnimationStop?: () => void;
97
98
// Display options
99
attribution?: ReactElement | false;
100
attributionPrefix?: ReactElement | false;
101
boxClassname?: string;
102
tileComponent?: TileComponent;
103
children?: React.ReactNode;
104
}
105
106
type Point = [number, number]; // [latitude, longitude]
107
```
108
109
[Map Component](./map.md)
110
111
### Markers and Overlays
112
113
Interactive markers and custom overlays for positioning content on the map with event handling capabilities.
114
115
```typescript { .api }
116
function Marker(props: MarkerProps): JSX.Element;
117
function Overlay(props: OverlayProps): JSX.Element;
118
119
interface MarkerProps extends PigeonProps {
120
color?: string;
121
payload?: any;
122
width?: number;
123
height?: number;
124
hover?: boolean;
125
style?: React.CSSProperties;
126
className?: string;
127
children?: JSX.Element;
128
onClick?: (params: MarkerEventParams) => void;
129
onContextMenu?: (params: MarkerEventParams) => void;
130
onMouseOver?: (params: MarkerEventParams) => void;
131
onMouseOut?: (params: MarkerEventParams) => void;
132
}
133
134
interface OverlayProps extends PigeonProps {
135
style?: React.CSSProperties;
136
className?: string;
137
children?: React.ReactNode;
138
}
139
```
140
141
[Markers and Overlays](./markers-overlays.md)
142
143
### GeoJSON Rendering
144
145
SVG-based rendering system for GeoJSON data with interactive features and styling capabilities.
146
147
```typescript { .api }
148
function GeoJson(props: GeoJsonProps): JSX.Element;
149
function GeoJsonLoader(props: GeoJsonLoaderProps): JSX.Element;
150
function GeoJsonFeature(props: GeoJsonProps): JSX.Element;
151
152
interface GeoJsonProps extends PigeonProps {
153
data?: any;
154
svgAttributes?: any;
155
styleCallback?: (feature: any, hover: boolean) => any;
156
hover?: any;
157
feature?: any;
158
className?: string;
159
style?: CSSProperties;
160
children?: React.ReactNode;
161
onClick?: (params: GeoJsonEventParams) => void;
162
onContextMenu?: (params: GeoJsonEventParams) => void;
163
onMouseOver?: (params: GeoJsonEventParams) => void;
164
onMouseOut?: (params: GeoJsonEventParams) => void;
165
}
166
167
interface GeoJsonLoaderProps extends GeoJsonProps {
168
link?: string;
169
}
170
```
171
172
[GeoJSON](./geojson.md)
173
174
### Draggable Elements
175
176
System for making map elements draggable with touch and mouse support.
177
178
```typescript { .api }
179
function Draggable(props: DraggableProps): JSX.Element;
180
181
interface DraggableProps extends PigeonProps {
182
className?: string;
183
style?: React.CSSProperties;
184
children?: React.ReactNode;
185
onDragStart?: (anchor: Point) => void;
186
onDragMove?: (anchor: Point) => void;
187
onDragEnd?: (anchor: Point) => void;
188
}
189
```
190
191
[Draggable Elements](./draggable.md)
192
193
### Map Controls
194
195
UI controls for map interaction including zoom buttons and other control elements.
196
197
```typescript { .api }
198
function ZoomControl(props: ZoomProps): JSX.Element;
199
200
interface ZoomProps extends PigeonProps {
201
style?: React.CSSProperties;
202
buttonStyle?: React.CSSProperties;
203
}
204
```
205
206
[Map Controls](./controls.md)
207
208
### Tile Providers
209
210
Built-in tile provider functions for popular map services with customization options.
211
212
```typescript { .api }
213
function osm(x: number, y: number, z: number): string;
214
function stamenToner(x: number, y: number, z: number, dpr?: number): string;
215
function stamenTerrain(x: number, y: number, z: number, dpr?: number): string;
216
function maptiler(apiKey: string, map?: string): TileProvider;
217
function stadiamaps(style?: string): TileProvider;
218
219
type TileProvider = (x: number, y: number, z: number, dpr?: number) => string;
220
```
221
222
[Tile Providers](./providers.md)
223
224
## Core Types
225
226
```typescript { .api }
227
// Base props for positioned elements
228
interface PigeonProps {
229
anchor?: Point;
230
offset?: Point;
231
left?: number;
232
top?: number;
233
mapState?: MapState;
234
mapProps?: MapProps;
235
latLngToPixel?: (latLng: Point, center?: Point, zoom?: number) => Point;
236
pixelToLatLng?: (pixel: Point, center?: Point, zoom?: number) => Point;
237
setCenterZoom?: (center: Point | null, zoom: number, zoomAround?: Point | null, animationDuration?: number) => void;
238
}
239
240
// Map bounds
241
interface Bounds {
242
ne: [number, number]; // northeast [lat, lng]
243
sw: [number, number]; // southwest [lat, lng]
244
}
245
246
// Current map state
247
interface MapState {
248
bounds: Bounds;
249
zoom: number;
250
center: Point;
251
width: number;
252
height: number;
253
}
254
255
// Event parameter types
256
interface ClickEvent {
257
event: MouseEvent;
258
latLng: Point;
259
pixel: Point;
260
}
261
262
interface BoundsChangeEvent {
263
center: Point;
264
zoom: number;
265
bounds: Bounds;
266
initial: boolean;
267
}
268
269
interface MarkerEventParams {
270
event: React.MouseEvent;
271
anchor: Point;
272
payload: any;
273
}
274
275
interface GeoJsonEventParams {
276
event: React.MouseEvent<SVGElement>;
277
anchor: Point;
278
payload: any;
279
}
280
281
// Tile system
282
interface Tile {
283
key: string;
284
url: string;
285
srcSet: string;
286
left: number;
287
top: number;
288
width: number;
289
height: number;
290
active: boolean;
291
}
292
293
type TileComponent = (props: TileComponentProps) => ReactElement;
294
295
interface TileComponentProps {
296
tile: Tile;
297
tileLoaded: () => void;
298
}
299
```