0
# Map Component
1

2
The Map component is the core interactive map that displays tile layers, handles user interactions, and manages map state. It provides a full-featured mapping experience with support for animations, event handling, and coordinate transformations.
3

4
## Capabilities
5

6
### Map Component
7

8
The main Map component that renders tiles and handles all map interactions.
9

10
```typescript { .api }
11
/**
12
 * Interactive map component with tile rendering and user interactions
13
 * @param props - Map configuration and event handlers
14
 * @returns JSX.Element representing the map
15
 */
16
function Map(props: MapProps): JSX.Element;
17

18
interface MapProps {
19
  // Position and size configuration
20
  center?: Point;
21
  defaultCenter?: Point;
22
  zoom?: number;
23
  defaultZoom?: number;
24
  width?: number;
25
  height?: number;
26
  defaultWidth?: number;
27
  defaultHeight?: number;
28

29
  // Tile provider configuration
30
  provider?: (x: number, y: number, z: number, dpr?: number) => string;
31
  dprs?: number[];
32

33
  // Animation settings
34
  animate?: boolean;
35
  animateMaxScreens?: number;
36

37
  // Zoom constraints
38
  minZoom?: number;
39
  maxZoom?: number;
40

41
  // Interaction controls
42
  metaWheelZoom?: boolean;
43
  metaWheelZoomWarning?: string;
44
  twoFingerDrag?: boolean;
45
  twoFingerDragWarning?: string;
46
  warningZIndex?: number;
47
  
48
  // Display settings
49
  attribution?: ReactElement | false;
50
  attributionPrefix?: ReactElement | false;
51
  zoomSnap?: boolean;
52
  mouseEvents?: boolean;
53
  touchEvents?: boolean;
54
  limitBounds?: 'center' | 'edge';
55
  boxClassname?: string;
56
  tileComponent?: TileComponent;
57

58
  // Event handlers
59
  onClick?: (params: {
60
    event: MouseEvent;
61
    latLng: Point;
62
    pixel: Point;
63
  }) => void;
64
  
65
  onBoundsChanged?: (params: {
66
    center: Point;
67
    zoom: number;
68
    bounds: Bounds;
69
    initial: boolean;
70
  }) => void;
71
  
72
  onAnimationStart?: () => void;
73
  onAnimationStop?: () => void;
74

75
  // Child elements
76
  children?: React.ReactNode;
77
}
78

79
// Default props values
80
static defaultProps = {
81
  animate: true,
82
  metaWheelZoom: false,
83
  metaWheelZoomWarning: 'Use META + wheel to zoom!',
84
  twoFingerDrag: false,
85
  twoFingerDragWarning: 'Use two fingers to move the map',
86
  zoomSnap: true,
87
  mouseEvents: true,
88
  touchEvents: true,
89
  warningZIndex: 100,
90
  animateMaxScreens: 5,
91
  minZoom: 1,
92
  maxZoom: 18,
93
  limitBounds: 'center',
94
  dprs: []
95
};
96
```
97

98
**Usage Examples:**
99

100
```tsx
101
import React, { useState } from "react";
102
import { Map } from "pigeon-maps";
103
import { osm } from "pigeon-maps/providers";
104

105
// Basic map
106
function BasicMap() {
107
  return (
108
    <Map 
109
      height={400} 
110
      center={[50.879, 4.6997]} 
111
      zoom={11}
112
      provider={osm}
113
    />
114
  );
115
}
116

117
// Controlled map with events
118
function ControlledMap() {
119
  const [center, setCenter] = useState([50.879, 4.6997]);
120
  const [zoom, setZoom] = useState(11);
121

122
  return (
123
    <Map
124
      height={400}
125
      center={center}
126
      zoom={zoom}
127
      onBoundsChanged={({ center, zoom }) => {
128
        setCenter(center);
129
        setZoom(zoom);
130
      }}
131
      onClick={({ latLng }) => {
132
        console.log('Clicked at:', latLng);
133
      }}
134
    />
135
  );
136
}
137

138
// Map with custom settings
139
function CustomMap() {
140
  return (
141
    <Map
142
      height={400}
143
      center={[50.879, 4.6997]}
144
      zoom={11}
145
      animate={true}
146
      metaWheelZoom={true}
147
      twoFingerDrag={true}
148
      minZoom={5}
149
      maxZoom={15}
150
      zoomSnap={false}
151
      attribution={false}
152
    />
153
  );
154
}
155
```
156

157
### Coordinate Conversion Methods
158

159
Methods for converting between geographic coordinates and pixel coordinates.
160

161
```typescript { .api }
162
/**
163
 * Convert pixel coordinates to latitude/longitude
164
 * @param pixel - Pixel coordinates [x, y]
165
 * @param center - Optional center point for calculation
166
 * @param zoom - Optional zoom level for calculation
167
 * @returns Geographic coordinates [lat, lng]
168
 */
169
pixelToLatLng(pixel: Point, center?: Point, zoom?: number): Point;
170

171
/**
172
 * Convert latitude/longitude to pixel coordinates
173
 * @param latLng - Geographic coordinates [lat, lng]
174
 * @param center - Optional center point for calculation
175
 * @param zoom - Optional zoom level for calculation
176
 * @returns Pixel coordinates [x, y]
177
 */
178
latLngToPixel(latLng: Point, center?: Point, zoom?: number): Point;
179
```
180

181
### Map Control Methods
182

183
Methods for programmatically controlling the map.
184

185
```typescript { .api }
186
/**
187
 * Set the map center and zoom level programmatically
188
 * @param center - New center coordinates or null to keep current
189
 * @param zoom - New zoom level
190
 * @param zoomAround - Optional point to zoom around
191
 * @param animationDuration - Duration of animation in milliseconds
192
 */
193
setCenterZoom(
194
  center: Point | null,
195
  zoom: number,
196
  zoomAround?: Point | null,
197
  animationDuration?: number
198
): void;
199

200
/**
201
 * Get the current map bounds
202
 * @param center - Optional center for bounds calculation
203
 * @param zoom - Optional zoom for bounds calculation
204
 * @returns Current map bounds
205
 */
206
getBounds(center?: Point, zoom?: number): Bounds;
207
```
208

209
### Map State Access
210

211
```typescript { .api }
212
/**
213
 * Current map state passed to child components
214
 */
215
interface MapState {
216
  bounds: Bounds;
217
  zoom: number;
218
  center: Point;
219
  width: number;
220
  height: number;
221
}
222

223
/**
224
 * Map bounds definition
225
 */
226
interface Bounds {
227
  ne: [number, number]; // northeast corner [lat, lng]
228
  sw: [number, number]; // southwest corner [lat, lng]
229
}
230
```
231

232
## Event Handling
233

234
### Click Events
235

236
```typescript { .api }
237
onClick?: (params: {
238
  event: MouseEvent;
239
  latLng: Point;
240
  pixel: Point;
241
}) => void;
242
```
243

244
The onClick handler receives the mouse event, the geographic coordinates where clicked, and the pixel coordinates.
245

246
### Bounds Change Events
247

248
```typescript { .api }
249
onBoundsChanged?: (params: {
250
  center: Point;
251
  zoom: number;
252
  bounds: Bounds;
253
  initial: boolean;
254
}) => void;
255
```
256

257
Fired when the map bounds change due to user interaction or programmatic changes. The `initial` flag indicates if this is the first bounds change event.
258

259
### Animation Events
260

261
```typescript { .api }
262
onAnimationStart?: () => void;
263
onAnimationStop?: () => void;
264
```
265

266
Called when map animations (zoom/pan transitions) start and stop.
267

268
## Advanced Configuration
269

270
### Custom Tile Components
271

272
```typescript { .api }
273
type TileComponent = (props: TileComponentProps) => ReactElement;
274

275
interface TileComponentProps {
276
  tile: Tile;
277
  tileLoaded: () => void;
278
}
279

280
interface Tile {
281
  key: string;
282
  url: string;
283
  srcSet: string;
284
  left: number;
285
  top: number;
286
  width: number;
287
  height: number;
288
  active: boolean;
289
}
290
```
291

292
### Interaction Warnings
293

294
The map can show warning overlays when users try to interact incorrectly (e.g., trying to zoom without meta key when `metaWheelZoom` is enabled).
295

296
```typescript { .api }
297
interface WarningProps {
298
  metaWheelZoom?: boolean;
299
  metaWheelZoomWarning?: string;
300
  twoFingerDrag?: boolean;
301
  twoFingerDragWarning?: string;
302
  warningZIndex?: number;
303
}
304
```
305

306
### Bounds Limiting
307

308
```typescript { .api }
309
limitBounds?: 'center' | 'edge';
310
```
311

312
- `'center'`: Limits the map so the center point stays within world bounds
313
- `'edge'`: Limits the map so the visible edge stays within world bounds