0
# Markers and Overlays
1

2
Interactive markers and custom overlays for positioning content on the map. Markers provide pre-styled map pins with hover effects and event handling, while Overlays offer a generic container for custom positioned content.
3

4
## Capabilities
5

6
### Marker Component
7

8
Interactive map markers with customizable appearance and comprehensive event handling.
9

10
```typescript { .api }
11
/**
12
 * Interactive map marker with customizable styling and events
13
 * @param props - Marker configuration and event handlers
14
 * @returns JSX.Element representing the marker
15
 */
16
function Marker(props: MarkerProps): JSX.Element;
17

18
interface MarkerProps extends PigeonProps {
19
  // Styling options
20
  color?: string;
21
  width?: number;
22
  height?: number;
23
  hover?: boolean;
24
  style?: React.CSSProperties;
25
  className?: string;
26
  
27
  // Data and content
28
  payload?: any;
29
  children?: JSX.Element;
30
  
31
  // Event handlers
32
  onClick?: (params: MarkerEventParams) => void;
33
  onContextMenu?: (params: MarkerEventParams) => void;
34
  onMouseOver?: (params: MarkerEventParams) => void;
35
  onMouseOut?: (params: MarkerEventParams) => void;
36
}
37

38
interface MarkerEventParams {
39
  event: React.MouseEvent;
40
  anchor: Point;
41
  payload: any;
42
}
43
```
44

45
**Usage Examples:**
46

47
```tsx
48
import React from "react";
49
import { Map, Marker } from "pigeon-maps";
50

51
// Basic marker
52
function BasicMarker() {
53
  return (
54
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
55
      <Marker anchor={[50.879, 4.6997]} />
56
    </Map>
57
  );
58
}
59

60
// Styled marker with events
61
function StyledMarker() {
62
  return (
63
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
64
      <Marker
65
        anchor={[50.879, 4.6997]}
66
        color="#ff6b6b"
67
        width={40}
68
        height={40}
69
        payload={{ name: "Brussels", id: 1 }}
70
        onClick={({ anchor, payload }) => {
71
          console.log(`Clicked ${payload.name} at`, anchor);
72
        }}
73
        onMouseOver={({ payload }) => {
74
          console.log(`Hovering over ${payload.name}`);
75
        }}
76
      />
77
    </Map>
78
  );
79
}
80

81
// Custom marker content
82
function CustomMarker() {
83
  return (
84
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
85
      <Marker anchor={[50.879, 4.6997]}>
86
        <div style={{
87
          background: 'white',
88
          padding: '5px',
89
          borderRadius: '3px',
90
          boxShadow: '0 2px 4px rgba(0,0,0,0.3)'
91
        }}>
92
          Custom Content
93
        </div>
94
      </Marker>
95
    </Map>
96
  );
97
}
98
```
99

100
### Overlay Component
101

102
Generic container for positioning custom content on the map at specific coordinates.
103

104
```typescript { .api }
105
/**
106
 * Generic overlay container for custom positioned content
107
 * @param props - Overlay configuration and content
108
 * @returns JSX.Element representing the overlay
109
 */
110
function Overlay(props: OverlayProps): JSX.Element;
111

112
interface OverlayProps extends PigeonProps {
113
  style?: React.CSSProperties;
114
  className?: string;
115
  children?: React.ReactNode;
116
}
117
```
118

119
**Usage Examples:**
120

121
```tsx
122
import React from "react";
123
import { Map, Overlay } from "pigeon-maps";
124

125
// Text overlay
126
function TextOverlay() {
127
  return (
128
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
129
      <Overlay anchor={[50.879, 4.6997]} offset={[10, -20]}>
130
        <div style={{
131
          background: 'rgba(0,0,0,0.8)',
132
          color: 'white',
133
          padding: '8px',
134
          borderRadius: '4px',
135
          fontSize: '14px'
136
        }}>
137
          Brussels, Belgium
138
        </div>
139
      </Overlay>
140
    </Map>
141
  );
142
}
143

144
// Complex overlay with multiple elements
145
function ComplexOverlay() {
146
  return (
147
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
148
      <Overlay anchor={[50.879, 4.6997]} offset={[0, -50]}>
149
        <div style={{
150
          background: 'white',
151
          border: '2px solid #333',
152
          borderRadius: '8px',
153
          padding: '12px',
154
          minWidth: '200px',
155
          boxShadow: '0 4px 8px rgba(0,0,0,0.2)'
156
        }}>
157
          <h3 style={{ margin: '0 0 8px 0' }}>Location Info</h3>
158
          <p style={{ margin: '0' }}>Brussels, Belgium</p>
159
          <button style={{ marginTop: '8px' }}>
160
            Get Directions
161
          </button>
162
        </div>
163
      </Overlay>
164
    </Map>
165
  );
166
}
167
```
168

169
## Positioning System
170

171
### PigeonProps Interface
172

173
Base props interface for all positioned elements on the map.
174

175
```typescript { .api }
176
interface PigeonProps {
177
  // Geographic positioning
178
  anchor?: Point;
179
  offset?: Point;
180
  
181
  // Pixel positioning (set automatically by Map)
182
  left?: number;
183
  top?: number;
184
  
185
  // Map context (provided automatically by Map)
186
  mapState?: MapState;
187
  mapProps?: MapProps;
188
  
189
  // Coordinate conversion functions (provided by Map)
190
  latLngToPixel?: (latLng: Point, center?: Point, zoom?: number) => Point;
191
  pixelToLatLng?: (pixel: Point, center?: Point, zoom?: number) => Point;
192
  setCenterZoom?: (
193
    center: Point | null,
194
    zoom: number,
195
    zoomAround?: Point | null,
196
    animationDuration?: number
197
  ) => void;
198
}
199
```
200

201
### Positioning Options
202

203
**Geographic Positioning:**
204
- `anchor`: Geographic coordinates `[lat, lng]` where the element should be positioned
205
- `offset`: Pixel offset `[x, y]` from the anchor point (positive x is right, positive y is down)
206

207
**Pixel Positioning:**
208
- `left` and `top`: Exact pixel coordinates (calculated automatically by the Map component)
209

210
### Map Context
211

212
Elements positioned on the map automatically receive:
213
- Current map state (bounds, zoom, center, dimensions)
214
- Map configuration props
215
- Coordinate conversion functions
216
- Map control functions
217

218
## Event Handling
219

220
### Marker Events
221

222
All marker events receive a `MarkerEventParams` object:
223

224
```typescript { .api }
225
interface MarkerEventParams {
226
  event: React.MouseEvent;
227
  anchor: Point;
228
  payload: any;
229
}
230
```
231

232
- `event`: The original React mouse event
233
- `anchor`: Geographic coordinates of the marker
234
- `payload`: Custom data attached to the marker
235

236
### Event Types
237

238
```typescript { .api }
239
// Mouse click (left button)
240
onClick?: (params: MarkerEventParams) => void;
241

242
// Right-click or context menu
243
onContextMenu?: (params: MarkerEventParams) => void;
244

245
// Mouse enters marker area
246
onMouseOver?: (params: MarkerEventParams) => void;
247

248
// Mouse leaves marker area
249
onMouseOut?: (params: MarkerEventParams) => void;
250
```
251

252
## Styling and Customization
253

254
### Marker Styling
255

256
```typescript { .api }
257
interface MarkerStyling {
258
  color?: string;        // Marker color (default: '#93C0D0')
259
  width?: number;        // Marker width in pixels
260
  height?: number;       // Marker height in pixels
261
  hover?: boolean;       // Controlled hover state
262
  style?: React.CSSProperties;  // Additional CSS styles
263
  className?: string;    // CSS class name
264
}
265
```
266

267
### Default Marker Dimensions
268

269
- Default width: 29 pixels
270
- Default height: 34 pixels
271
- Aspect ratio is maintained when only width or height is specified
272

273
### Hover Effects
274

275
Markers support automatic and controlled hover states:
276

277
```tsx
278
// Automatic hover (internal state)
279
<Marker anchor={[50.879, 4.6997]} />
280

281
// Controlled hover (external state)
282
const [isHovered, setIsHovered] = useState(false);
283
<Marker 
284
  anchor={[50.879, 4.6997]} 
285
  hover={isHovered}
286
  onMouseOver={() => setIsHovered(true)}
287
  onMouseOut={() => setIsHovered(false)}
288
/>
289
```
290

291
## CSS Classes
292

293
### Default Classes
294

295
- Markers: `pigeon-click-block` (prevents map clicks when clicking marker)
296
- Overlays: `pigeon-click-block` (prevents map clicks when clicking overlay)
297

298
### Custom Classes
299

300
```tsx
301
<Marker 
302
  anchor={[50.879, 4.6997]} 
303
  className="my-custom-marker"
304
/>
305

306
<Overlay 
307
  anchor={[50.879, 4.6997]} 
308
  className="my-custom-overlay"
309
>
310
  Content
311
</Overlay>
312
```
313

314
## Performance Considerations
315

316
- Markers and overlays are re-rendered when the map moves/zooms
317
- Use React.memo() for expensive custom marker content
318
- Consider virtualization for large numbers of markers
319
- Markers automatically prevent event bubbling to the map