0
# GeoJSON
1

2
SVG-based rendering system for GeoJSON data with interactive features and styling capabilities. Supports all GeoJSON geometry types including Points, LineStrings, Polygons, and their Multi- variants, with comprehensive event handling and dynamic styling.
3

4
## Capabilities
5

6
### GeoJson Component
7

8
Main component for rendering GeoJSON data as interactive SVG overlays.
9

10
```typescript { .api }
11
/**
12
 * Renders GeoJSON data as interactive SVG overlays
13
 * @param props - GeoJSON configuration and styling options
14
 * @returns JSX.Element representing the GeoJSON overlay
15
 */
16
function GeoJson(props: GeoJsonProps): JSX.Element;
17

18
interface GeoJsonProps extends PigeonProps {
19
  // Data and configuration
20
  data?: any;
21
  svgAttributes?: any;
22
  styleCallback?: (feature: any, hover: boolean) => any;
23
  hover?: any;
24
  feature?: any;
25
  
26
  // Styling
27
  className?: string;
28
  style?: CSSProperties;
29
  
30
  // Content
31
  children?: React.ReactNode;
32
  
33
  // Event handlers
34
  onClick?: (params: GeoJsonEventParams) => void;
35
  onContextMenu?: (params: GeoJsonEventParams) => void;
36
  onMouseOver?: (params: GeoJsonEventParams) => void;
37
  onMouseOut?: (params: GeoJsonEventParams) => void;
38
}
39

40
interface GeoJsonEventParams {
41
  event: React.MouseEvent<SVGElement>;
42
  anchor: Point;
43
  payload: any;
44
}
45
```
46

47
**Usage Examples:**
48

49
```tsx
50
import React from "react";
51
import { Map, GeoJson } from "pigeon-maps";
52

53
// Basic GeoJSON rendering
54
function BasicGeoJson() {
55
  const geoJsonData = {
56
    type: "FeatureCollection",
57
    features: [
58
      {
59
        type: "Feature",
60
        geometry: {
61
          type: "Point",
62
          coordinates: [4.6997, 50.879]
63
        },
64
        properties: {
65
          name: "Brussels"
66
        }
67
      }
68
    ]
69
  };
70

71
  return (
72
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
73
      <GeoJson data={geoJsonData} />
74
    </Map>
75
  );
76
}
77

78
// Styled GeoJSON with events
79
function StyledGeoJson() {
80
  const polygonData = {
81
    type: "FeatureCollection",
82
    features: [
83
      {
84
        type: "Feature",
85
        geometry: {
86
          type: "Polygon",
87
          coordinates: [[
88
            [4.68, 50.87],
89
            [4.72, 50.87],
90
            [4.72, 50.89],
91
            [4.68, 50.89],
92
            [4.68, 50.87]
93
          ]]
94
        },
95
        properties: {
96
          name: "Brussels Center"
97
        }
98
      }
99
    ]
100
  };
101

102
  return (
103
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
104
      <GeoJson
105
        data={polygonData}
106
        svgAttributes={{
107
          fill: 'rgba(255, 0, 0, 0.3)',
108
          stroke: 'red',
109
          strokeWidth: '2'
110
        }}
111
        onClick={({ payload }) => {
112
          console.log('Clicked feature:', payload.properties.name);
113
        }}
114
      />
115
    </Map>
116
  );
117
}
118
```
119

120
### GeoJsonLoader Component
121

122
Component that fetches GeoJSON data from a URL and renders it.
123

124
```typescript { .api }
125
/**
126
 * Fetches and renders GeoJSON data from a URL
127
 * @param props - GeoJSON loader configuration
128
 * @returns JSX.Element representing the loaded GeoJSON or null while loading
129
 */
130
function GeoJsonLoader(props: GeoJsonLoaderProps): JSX.Element;
131

132
interface GeoJsonLoaderProps extends GeoJsonProps {
133
  link?: string;
134
}
135
```
136

137
**Usage Example:**
138

139
```tsx
140
import React from "react";
141
import { Map, GeoJsonLoader } from "pigeon-maps";
142

143
function RemoteGeoJson() {
144
  return (
145
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
146
      <GeoJsonLoader
147
        link="https://example.com/data.geojson"
148
        svgAttributes={{
149
          fill: 'rgba(0, 255, 0, 0.3)',
150
          stroke: 'green',
151
          strokeWidth: '1'
152
        }}
153
      />
154
    </Map>
155
  );
156
}
157
```
158

159
### GeoJsonFeature Component
160

161
Component for rendering individual GeoJSON features with interactive capabilities.
162

163
```typescript { .api }
164
/**
165
 * Renders individual GeoJSON features with interactive capabilities
166
 * @param props - Feature configuration and styling
167
 * @returns JSX.Element representing the feature
168
 */
169
function GeoJsonFeature(props: GeoJsonProps): JSX.Element;
170
```
171

172
## Geometry Components
173

174
### Point Rendering
175

176
```typescript { .api }
177
/**
178
 * Renders GeoJSON Point geometry
179
 * @param props - Point geometry configuration
180
 * @returns JSX.Element representing the point
181
 */
182
function PointComponent(props: GeometryProps): JSX.Element;
183

184
/**
185
 * Renders GeoJSON MultiPoint geometry
186
 * @param props - MultiPoint geometry configuration
187
 * @returns JSX.Element representing multiple points
188
 */
189
function MultiPoint(props: GeometryProps): JSX.Element;
190

191
interface GeometryProps {
192
  coordinates?: [number, number] | Array<[number, number]> | Array<Array<[number, number]>> | Array<Array<Array<[number, number]>>>;
193
  latLngToPixel?: (latLng: Point, center?: Point, zoom?: number) => Point;
194
  svgAttributes?: SVGProps<SVGElement>;
195
  geometry?: GeoJsonGeometry;
196
}
197
```
198

199
### Line Rendering
200

201
```typescript { .api }
202
/**
203
 * Renders GeoJSON LineString geometry
204
 * @param props - LineString geometry configuration
205
 * @returns JSX.Element representing the line
206
 */
207
function LineString(props: GeometryProps): JSX.Element;
208

209
/**
210
 * Renders GeoJSON MultiLineString geometry
211
 * @param props - MultiLineString geometry configuration
212
 * @returns JSX.Element representing multiple lines
213
 */
214
function MultiLineString(props: GeometryProps): JSX.Element;
215
```
216

217
### Polygon Rendering
218

219
```typescript { .api }
220
/**
221
 * Renders GeoJSON Polygon geometry
222
 * @param props - Polygon geometry configuration
223
 * @returns JSX.Element representing the polygon
224
 */
225
function Polygon(props: GeometryProps): JSX.Element;
226

227
/**
228
 * Renders GeoJSON MultiPolygon geometry
229
 * @param props - MultiPolygon geometry configuration
230
 * @returns JSX.Element representing multiple polygons
231
 */
232
function MultiPolygon(props: GeometryProps): JSX.Element;
233
```
234

235
### Geometry Collection
236

237
```typescript { .api }
238
/**
239
 * Renders GeoJSON GeometryCollection
240
 * @param props - GeometryCollection configuration
241
 * @returns JSX.Element representing the collection
242
 */
243
function GeometryCollection(props: GeometryProps): JSX.Element;
244

245
interface GeoJsonGeometry {
246
  type: string;
247
  coordinates?: [number, number] | Array<[number, number]> | Array<Array<[number, number]>> | Array<Array<Array<[number, number]>>>;
248
  geometries?: Array<GeoJsonGeometry>;
249
}
250
```
251

252
## Styling System
253

254
### Default SVG Attributes
255

256
```typescript { .api }
257
const defaultSvgAttributes = {
258
  fill: '#93c0d099',
259
  strokeWidth: '2',
260
  stroke: 'white',
261
  r: '30'
262
};
263
```
264

265
### Static Styling
266

267
```tsx
268
<GeoJson
269
  data={geoJsonData}
270
  svgAttributes={{
271
    fill: 'rgba(255, 0, 0, 0.5)',
272
    stroke: 'darkred',
273
    strokeWidth: '3',
274
    strokeDasharray: '5,5'
275
  }}
276
/>
277
```
278

279
### Dynamic Styling with Callbacks
280

281
```typescript { .api }
282
styleCallback?: (feature: any, hover: boolean) => any;
283
```
284

285
**Usage Example:**
286

287
```tsx
288
function DynamicStyledGeoJson() {
289
  const styleCallback = (feature, hover) => {
290
    const baseStyle = {
291
      fill: feature.properties.color || '#93c0d099',
292
      stroke: 'white',
293
      strokeWidth: '2'
294
    };
295
    
296
    if (hover) {
297
      return {
298
        ...baseStyle,
299
        fill: '#ff000080',
300
        strokeWidth: '4'
301
      };
302
    }
303
    
304
    return baseStyle;
305
  };
306

307
  return (
308
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
309
      <GeoJson
310
        data={geoJsonData}
311
        styleCallback={styleCallback}
312
        onClick={({ payload }) => {
313
          console.log('Feature properties:', payload.properties);
314
        }}
315
      />
316
    </Map>
317
  );
318
}
319
```
320

321
### Custom Path Styling for Points
322

323
Points can use custom SVG paths instead of circles:
324

325
```tsx
326
<GeoJson
327
  data={pointData}
328
  svgAttributes={{
329
    fill: '#ff6b6b',
330
    stroke: 'white',
331
    strokeWidth: '2',
332
    path: 'c-5,-10 -10,-10 -10,0 0,10 10,10 10,0z' // Custom marker shape
333
  }}
334
/>
335
```
336

337
## Event Handling
338

339
### Event Parameters
340

341
All GeoJSON events receive a `GeoJsonEventParams` object:
342

343
```typescript { .api }
344
interface GeoJsonEventParams {
345
  event: React.MouseEvent<SVGElement>;
346
  anchor: Point;
347
  payload: any; // The GeoJSON feature object
348
}
349
```
350

351
### Event Types
352

353
```typescript { .api }
354
// Mouse click on feature
355
onClick?: (params: GeoJsonEventParams) => void;
356

357
// Right-click or context menu on feature
358
onContextMenu?: (params: GeoJsonEventParams) => void;
359

360
// Mouse enters feature area
361
onMouseOver?: (params: GeoJsonEventParams) => void;
362

363
// Mouse leaves feature area
364
onMouseOut?: (params: GeoJsonEventParams) => void;
365
```
366

367
### Event Example
368

369
```tsx
370
function InteractiveGeoJson() {
371
  return (
372
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
373
      <GeoJson
374
        data={geoJsonData}
375
        onClick={({ event, anchor, payload }) => {
376
          console.log('Clicked at coordinates:', anchor);
377
          console.log('Feature data:', payload);
378
          console.log('Mouse event:', event);
379
        }}
380
        onMouseOver={({ payload }) => {
381
          console.log('Hovering over:', payload.properties.name);
382
        }}
383
      />
384
    </Map>
385
  );
386
}
387
```
388

389
## Hover States
390

391
### Automatic Hover
392

393
Features automatically track hover state internally:
394

395
```tsx
396
<GeoJson
397
  data={geoJsonData}
398
  styleCallback={(feature, hover) => ({
399
    fill: hover ? '#ff0000' : '#0000ff',
400
    stroke: 'white'
401
  })}
402
/>
403
```
404

405
### Controlled Hover
406

407
```tsx
408
function ControlledHoverGeoJson() {
409
  const [hoveredFeature, setHoveredFeature] = useState(null);
410

411
  return (
412
    <Map height={400} center={[50.879, 4.6997]} zoom={11}>
413
      <GeoJson
414
        data={geoJsonData}
415
        hover={hoveredFeature}
416
        onMouseOver={({ payload }) => setHoveredFeature(payload)}
417
        onMouseOut={() => setHoveredFeature(null)}
418
        styleCallback={(feature, hover) => ({
419
          fill: hover ? '#ff0000' : '#0000ff'
420
        })}
421
      />
422
    </Map>
423
  );
424
}
425
```
426

427
## Performance Considerations
428

429
- GeoJSON is rendered as SVG, which performs well for moderate numbers of features
430
- For large datasets (>1000 features), consider:
431
  - Simplifying geometries at lower zoom levels
432
  - Using feature filtering based on map bounds
433
  - Implementing level-of-detail rendering
434
- Complex polygons with many vertices may impact performance
435
- SVG styling is more performant than DOM manipulation for dynamic styling