React Simple Maps

https://github.com/zcreativelabs/react-simple-maps
Admin
React Simple Maps is a declarative React component library for creating customizable SVG maps and...
Tokens:60,459
Snippets:302
Trust Score:8
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install react-simple-maps with npm

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/README.md

Install the react-simple-maps package using npm. This is the standard installation command for the library.

```bash
$ npm install react-simple-maps
```

--------------------------------

### Basic usage example: FlightRoute

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Line.md

A basic example showing how to render a straight line between two geographic points (Amsterdam and New York) using the from and to props. The line is styled with a custom stroke color and width.

```jsx
import { ComposableMap, Line } from "react-simple-maps"

export const FlightRoute = () => (
  <ComposableMap>
    {/* Straight line Amsterdam <-> New York */}
    <Line
      from={[4.8994, 52.3791]}
      to={[-74.006, 40.7128]}
      stroke="#e76f51"
      strokeWidth={2}
    />
  </ComposableMap>
)
```

--------------------------------

### Polyline usage example: Route3D

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Line.md

An example showing how to render a polyline through multiple geographic points using the coordinates prop. The coordinates array overrides from/to and creates a path through all points.

```jsx
import { ComposableMap, Line } from "react-simple-maps"

export const Route3D = () => (
  <ComposableMap>
    <Line
      coordinates={[
        [-74.006, 40.7128], // New York
        [-0.1276, 51.5072], // London
        [2.3522, 48.8566],  // Paris
      ]}
      stroke="#264653"
      strokeWidth={1.5}
      fill="none"
    />
  </ComposableMap>
)
```

--------------------------------

### Basic usage of ZoomableGroup

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/ZoomableGroup.md

Example showing how to use ZoomableGroup with ComposableMap, Geographies, and Geography. It sets center and zoom props and renders a world map from a topojson file.

```jsx
import { ComposableMap, ZoomableGroup, Geographies, Geography } from "react-simple-maps"

export const ZoomableMap = () => (
  <ComposableMap>
    <ZoomableGroup center={[10, 20]} zoom={3}>
      <Geographies geography="/world-topo.json">
        {({ geographies }) =>
          geographies.map((geo) => (
            <Geography key={geo.rsmKey} geography={geo} fill="#ddd" stroke="#333" />
          ))
        }
      </Geographies>
    </ZoomableGroup>
  </ComposableMap>
)
```

--------------------------------

### Custom step example for Graticule

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Graticule.md

Uses a custom step of [20,20] to create a coarser grid. Also sets stroke and strokeWidth. The ComposableMap uses the default projection.

```jsx
import { ComposableMap, Graticule } from "react-simple-maps"

export const CoarseGrid = () => (
  <ComposableMap>
    <Graticule step={[20, 20]} stroke="#555" strokeWidth={0.5} />
  </ComposableMap>
)
```

--------------------------------

### Basic usage of Marker with ComposableMap

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Marker.md

Shows how to place markers on a map using the Marker component. Each Marker takes coordinates and renders a circle and text label. This example places markers for Amsterdam and Paris.

```jsx
import { ComposableMap, Marker } from "react-simple-maps"

export const CitiesMap = () => (
  <ComposableMap>
    <Marker coordinates={[4.8994, 52.3791]}>
      <circle r={6} fill="#e63946" />
      <text textAnchor="middle" y={-12}>Amsterdam</text>
    </Marker>
    <Marker coordinates={[2.3522, 48.8566]}>
      <circle r={6} fill="#e63946" />
      <text textAnchor="middle" y={-12}>Paris</text>
    </Marker>
  </ComposableMap>
)
```

--------------------------------

### Basic usage example (Globe component)

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Sphere.md

Shows how to render a globe with a sphere outline and graticule. The Sphere component is used inside a ComposableMap with a geoOrthographic projection. The sphere is filled with a light blue and stroked with a dark blue.

```jsx
import { ComposableMap, Sphere, Graticule, Geographies, Geography } from "react-simple-maps"

export const Globe = () => (
  <ComposableMap projection="geoOrthographic">
    <Sphere fill="#dbe9f6" stroke="#1b4965" strokeWidth={1} />
    <Graticule stroke="#9bb8dc" />
  </ComposableMap>
)
```

--------------------------------

### Basic Annotation usage with Marker

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Annotation.md

A JSX example showing how to use the Annotation component with a subject and offset, along with a Marker to display a point on the map. The Annotation renders a text label and the Marker renders a circle.

```jsx
import { ComposableMap, Annotation, Marker } from "react-simple-maps"

export const AnnotatedMap = () => (
  <ComposableMap>
    <Annotation subject={[4.8994, 52.3791]} dx={50} dy={-40}>
      <text textAnchor="middle">Amsterdam</text>
    </Annotation>
    <Marker coordinates={[4.8994, 52.3791]}>
      <circle r={4} fill="#d1495b" />
    </Marker>
  </ComposableMap>
)
```

--------------------------------

### StyledAnnotation example with custom connector styling and curve

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Annotation.md

Use this JSX example to render an Annotation with a custom connector path (stroke, width, dasharray) and curve. The subject is set to New York City coordinates, and the annotation includes a custom label group. Requires ComposableMap and Annotation imports from react-simple-maps.

```jsx
import { ComposableMap, Annotation } from "react-simple-maps"

export const StyledAnnotation = () => (
  <ComposableMap>
    <Annotation
      subject={[-74.006, 40.7128]}
      dx={60}
      dy={-60}
      curve={[0.4, 0.4]}
      connectorProps={{
        stroke: "#ff6b6b",
        strokeWidth: 2,
        strokeDasharray: "4 2",
      }}
    >
      <g>
        <rect x={-40} y={-18} width={80} height={24} rx={4} fill="#fff" stroke="#333" />
        <text textAnchor="middle" dominantBaseline="central">NYC</text>
      </g>
    </Annotation>
  </ComposableMap>
)
```

--------------------------------

### Basic usage of Geography with ComposableMap

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Geography.md

A basic example rendering a world map using ComposableMap, Geographies, and Geography. It maps over geographies and renders each with fill, stroke, and strokeWidth props.

```jsx
import { ComposableMap, Geographies, Geography } from "react-simple-maps"

const geoUrl = "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json"

export const WorldMap = () => (
  <ComposableMap>
    <Geographies geography={geoUrl}>
      {({ geographies }) =>
        geographies.map((geo) => (
          <Geography
            key={geo.rsmKey}
            geography={geo}
            fill="#e8e8e8"
            stroke="#555"
            strokeWidth={0.5}
          />
        ))
      }
    </Geographies>
  </ComposableMap>
)
```

--------------------------------

### LineString geometry example

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Line.md

The geometry object passed to the path generator. It is a LineString with coordinates either from the coordinates prop or from the from/to pair.

```json
{ "type": "LineString", "coordinates": coordinates || [from, to] }
```

--------------------------------

### Error handling: standalone provider misuse

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/ZoomPanProvider.md

Demonstrates that useZoomPanContext throws an error when no provider ancestor exists. The example shows a provider with an explicit value and a component that reads the transformString.

```tsx
import { ZoomPanProvider, useZoomPanContext } from "react-simple-maps"

const ShowTransform = () => {
  // Throws Error("useZoomPanContext must be used within ZoomPanProvider")
  // unless a provider ancestor exists.
  const { transformString } = useZoomPanContext()
  return <div>{transformString}</div>
}

export const WithProvider = () => (
  <ZoomPanProvider value={{ x: 10, y: 20, k: 2, transformString: "translate(10 20) scale(2)" }}>
    <ShowTransform /> {/* renders "translate(10 20) scale(2)" */}
  </ZoomPanProvider>
)
```

--------------------------------

### Basic usage of ComposableMap with geoMercator projection

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/ComposableMap.md

A minimal example that renders a world map using the ComposableMap component with a string projection 'geoMercator' and loads geographic data from a URL.

```jsx
import { ComposableMap, Geographies, Geography } from "react-simple-maps"

const geoUrl = "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json"

export const WorldMap = () => (
  <ComposableMap width={900} height={500} projection="geoMercator">
    <Geographies geography={geoUrl}>
      {({ geographies }) =>
        geographies.map((geo) => (
          <Geography key={geo.rsmKey} geography={geo} />
        ))
      }
    </Geographies>
  </ComposableMap>
)
```

--------------------------------

### Clipped map content example (ClippedGlobe component)

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Sphere.md

Demonstrates how to use the Sphere's clipPath to clip map content (Geographies) to the sphere. The Sphere is given a custom id 'sphere-clip', and the Geographies group uses clipPath="url(#sphere-clip)" to clip the landmasses to the globe.

```jsx
import { ComposableMap, Sphere, Geographies, Geography } from "react-simple-maps"

export const ClippedGlobe = () => (
  <ComposableMap projection="geoOrthographic">
    <Sphere id="sphere-clip" fill="#dbe9f6" stroke="#1b4965" />
    <Geographies geography="/land-110m.json">
      {({ geographies }) => (
        <g clipPath="url(#sphere-clip)">
          {geographies.map((geo) => (
            <Geography key={geo.rsmKey} geography={geo} fill="#2a6f97" stroke="#fff" />
          ))}
        </g>
      )}
    </Geographies>
  </ComposableMap>
)
```

--------------------------------

### TrackedMap component with ZoomableGroup event callbacks

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/ZoomableGroup.md

Example showing a ComposableMap with a ZoomableGroup that logs movement events. The onMoveStart, onMove, and onMoveEnd callbacks receive coordinates and zoom/transform data. Requires a valid GeoJSON file at '/usa-topo.json'.

```jsx
import { ComposableMap, ZoomableGroup, Geographies, Geography } from "react-simple-maps"

export const TrackedMap = () => (
  <ComposableMap>
    <ZoomableGroup
      minZoom={0.5}
      maxZoom={16}
      translateExtent={[[-500, -500], [1300, 1100]]}
      onMoveStart={({ coordinates }, event) =>
        console.log("started at", coordinates, "k =", event.transform.k)
      }
      onMove={({ x, y, zoom, dragging }) =>
        console.log("move", { x, y, zoom, dragging })
      }
      onMoveEnd={({ coordinates, zoom }) =>
        console.log("ended at", coordinates, "k =", zoom)
      }
    >
      <Geographies geography="/usa-topo.json">
        {({ geographies }) =>
          geographies.map((geo) => (
            <Geography key={geo.rsmKey} geography={geo} />
          ))
        }
      </Geographies>
    </ZoomableGroup>
  </ComposableMap>
)
```

--------------------------------

### Sphere component source code (src/core/components/Sphere.ts)

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Sphere.md

The full implementation of the Sphere component. It uses useMapContext() to get the projection path, memoizes the sphere path with useMemo, and returns a Fragment with a clipPath definition and a path element. The component is wrapped in React.memo.

```tsx
// src/core/components/Sphere.ts (lines 5–43)
const Sphere = forwardRef<SVGPathElement, SphereProps>(
  (
    {
      id = "rsm-sphere",
      fill = "transparent",
      stroke = "currentcolor",
      className = "",
      ...restProps
    },
    ref
  ) => {
    const { path } = useMapContext()
    const spherePath = useMemo(() => path({ type: "Sphere" }), [path])

    return React.createElement(
      Fragment,
      null,
      React.createElement(
        "defs",
        null,
        React.createElement(
          "clipPath",
          { id },
          React.createElement("path", { d: spherePath })
        )
      ),
      React.createElement("path", {
        ref,
        d: spherePath,
        fill,
        stroke,
        style: { pointerEvents: "none" },
        className: `rsm-sphere ${className}`,
        ...restProps,
      })
    )
  }
)
```

--------------------------------

### Annotation component implementation (src/core/components/Annotation.ts)

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Annotation.md

The full implementation of the Annotation component. It uses useMapContext to get the projection, projects the subject, and returns null if projection fails. The group is translated to subject + (dx, dy) and a connector path is drawn from that origin back to the subject. The connector path is created by createConnectorPath(dx, dy, curve).

```tsx
// src/core/components/Annotation.ts (lines 6–46)
const Annotation = forwardRef<SVGGElement, AnnotationProps>(
  (
    {
      subject,
      children,
      connectorProps,
      dx = 30,
      dy = 30,
      curve = 0,
      className = "",
      ...restProps
    },
    ref
  ) => {
    const { projection } = useMapContext()
    const projected = projection(subject)
    const connectorPath = createConnectorPath(dx, dy, curve)

    if (!projected) return null

    const [x, y] = projected

    return React.createElement(
      "g",
      {
        ref,
        transform: `translate(${x + dx}, ${y + dy})`,
        className: `rsm-annotation ${className}`,
        ...restProps,
      },
      React.createElement("path", {
        d: connectorPath,
        fill: "transparent",
        stroke: "#000",
        ...connectorProps,
      }),
      children
    )
  }
)

```

--------------------------------

### Basic usage with MapProvider and useMapContext

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/MapProvider.md

Shows how to use MapProvider with a projection and useMapContext to access the context and project a point. The ProbedComponent uses the path function to project a coordinate and renders a path element.

```jsx
import { MapProvider, useMapContext } from "react-simple-maps"

const ProbedComponent = () => {
  const { width, height, projection, path } = useMapContext()
  const d = path({ type: "Point", coordinates: [4.8994, 52.3791] })
  return <path d={d} fill="tomato" /> // projected point
}

export const ManualMap = () => (
  <svg viewBox="0 0 800 600" className="rsm-svg">
    <MapProvider projection="geoEquirectangular" width={800} height={600}>
      <ProbedComponent />
    </MapProvider>
  </svg>
)
```

--------------------------------

### Import MapProvider, MapContext, useMapContext

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/MapProvider.md

Import the context-related exports from the package. Use either the main package or the core subpath.

```ts
import { MapProvider, MapContext, useMapContext } from "react-simple-maps"
```

```ts
from "react-simple-maps/core"
```

--------------------------------

### Interactive Geography with hover state

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Geography.md

An example showing how to use rest props for interaction. It tracks a hovered geography using useState and changes fill color on mouse enter/leave.

```jsx
import { useState } from "react"
import { ComposableMap, Geographies, Geography } from "react-simple-maps"

export const InteractiveMap = () => {
  const [hovered, setHovered] = useState(null)

  return (
    <ComposableMap>
      <Geographies geography="/world-topo.json">
        {({ geographies }) =>
          geographies.map((geo) => (
            <Geography
              key={geo.rsmKey}
              geography={geo}
              fill={hovered === geo.rsmKey ? "#f4a261" : "#e9c46a"}
              stroke="#264653"
              onMouseEnter={() => setHovered(geo.rsmKey)}
              onMouseLeave={() => setHovered(null)}
            />
          ))
        }
      </Geographies>
    </ComposableMap>
  )
}
```

--------------------------------

### Graticule component implementation (src/core/components/Graticule.ts)

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Graticule.md

The source code of the Graticule component. It uses useMapContext to get the path generator and renders an SVG path with the graticule geometry. The component is memoized and forwards restProps.

```tsx
// src/core/components/Graticule.ts (lines 6–28)
const Graticule = forwardRef<SVGPathElement, GraticuleProps>(
  (
    {
      fill = "transparent",
      stroke = "currentcolor",
      step = [10, 10],
      className = "",
      ...restProps
    },
    ref
  ) => {
    const { path } = useMapContext()
    return React.createElement("path", {
      ref,
      d: path(geoGraticule().step(step)()),
      fill,
      stroke,
      className: `rsm-graticule ${className}`,
      ...restProps,
    })
  }
)
```

--------------------------------

### createConnectorPath(dx, dy, curve)

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Annotation.md

Builds a quadratic bezier path from the label origin back to the subject. The path is used by the Annotation component to draw a connector line.

```APIDOC
## createConnectorPath(dx, dy, curve)

### Description
Builds a quadratic bezier path from the label origin back to the subject. The path is used by the Annotation component to draw a connector line.

### Method
Function

### Signature
`createConnectorPath(dx, dy, curve)`

### Parameters
- **dx** (number) - The horizontal offset from the subject to the label origin. Default is 30 when called with no arguments.
- **dy** (number) - The vertical offset from the subject to the label origin. Default is 30 when called with no arguments.
- **curve** (number) - Controls the curvature of the connector. Default is 0.5 when called with no arguments. Higher values bow the connector out.

### Returns
A string representing the SVG path data for the quadratic bezier connector.

### Example
```
M0,0 Q -dx/2 - curveX, -dy/2 + curveY  -dx,-dy
```
where `curveX = (dx / 2) * curvature[0]` and `curveY = (dy / 2) * curvature[1]`.
```

--------------------------------

### UseZoomPanProps

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/types.md

Configuration props for the useZoomPan hook, including center, zoom, extents, and event handlers.

```APIDOC
## UseZoomPanProps

### Description
Accepted by: `useZoomPan`.

### Type
```ts
export interface UseZoomPanProps {
  center?: [number, number]
  zoom?: number
  translateExtent?: Array<[number, number]>
  scaleExtent?: [number, number]
  filterZoomEvent?: (event: Event) => boolean
  onMoveStart?: (props: ZoomPanCallbackProps, event: ZoomGestureEvent) => void
  onMove?: (props: ZoomPanCallbackProps, event: ZoomGestureEvent) => void
  onMoveEnd?: (props: ZoomPanCallbackProps, event: ZoomGestureEvent) => void
}
```

### Fields
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| center | `[number, number]` | no | `[0, 0]` | Geographic center. |
| zoom | `number` | no | `1` | Zoom level. |
| translateExtent | `Array<[number, number]>` | no | `[[-Infinity, -Infinity], [Infinity, Infinity]]` | Pan bounds. |
| scaleExtent | `[number, number]` | no | `[1, 8]` | Zoom bounds. |
| filterZoomEvent | `(event: Event) => boolean` | no | internal filter | Gesture filter. |
| onMoveStart | `(props, event) => void` | no | — | `"start"` handler. |
| onMove | `(props, event) => void` | no | — | `"zoom"` handler. |
| onMoveEnd | `(props, event) => void` | no | — | `"end"` handler. |
```

--------------------------------

### UseZoomPanReturn

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/types.md

Return value of the useZoomPan hook, providing a ref, current position, and transform string.

```APIDOC
## UseZoomPanReturn

### Description
Returned by: `useZoomPan`.

### Type
```ts
export interface UseZoomPanReturn {
  mapRef: React.MutableRefObject<SVGGElement | null>
  position: ZoomPanPosition
  transformString: string
}
```

### Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| mapRef | `React.MutableRefObject<SVGGElement \| null>` | yes | Ref the zoom behavior binds to. |
| position | `ZoomPanPosition` | yes | Current transform. |
| transformString | `string` | yes | SVG transform string. |
```

--------------------------------

### Export MapContext and MapProvider, useMapContext

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/MapProvider.md

Shows the exports from the source file. MapContext is created with createContext, and MapProvider and useMapContext are exported.

```ts
// src/core/components/MapProvider.ts (line 24)
export const MapContext = createContext<MapContextType | undefined>(undefined)
```

```ts
// line 128
export { MapProvider, useMapContext }
```

--------------------------------

### Geographies component implementation

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Geographies.md

The Geographies component uses useMapContext to get path and projection, and useGeographies to fetch and parse the geography. It renders a <g> element with class 'rsm-geographies' and calls the children render-prop only when geographies are non-empty.

```tsx
// src/core/components/Geographies.ts (lines 6–30)
const Geographies = forwardRef<SVGGElement, GeographiesProps>(
  (
    { geography, children, parseGeographies, className = "", ...restProps },
    ref
  ) => {
    const { path, projection } = useMapContext()
    const { geographies, outline, borders } = useGeographies({
      geography,
      parseGeographies,
    })

    return React.createElement(
      "g",
      {
        ref,
        className: `rsm-geographies ${className}`,
        ...restProps,
      },
      geographies &&
        geographies.length > 0 &&
        children({ geographies, outline, borders, path, projection })
    )
  }
)
```

--------------------------------

### Basic usage of useGeographies with a URL

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/useGeographies.md

Loads world-atlas TopoJSON from a CDN URL. Returns geographies, outline, and borders. Renders them as SVG paths inside a ComposableMap. The outline and borders are optional and use svgPath.

```tsx
import { ComposableMap, useGeographies } from "react-simple-maps"

const geoUrl = "https://cdn.jsdelivr.net/npm/world-atlas@2/countries-110m.json"

export const DataDrivenMap = () => {
  const { geographies, outline, borders } = useGeographies({ geography: geoUrl })

  return (
    <ComposableMap>
      {outline && <path d={outline.svgPath ?? ""} fill="none" stroke="#333" />}
      {borders && <path d={borders.svgPath ?? ""} fill="none" stroke="#999" />}
      {geographies.map((geo) => (
        <path key={geo.rsmKey} d={geo.svgPath ?? ""} fill="#eee" />
      ))}
    </ComposableMap>
  )
}
```

--------------------------------

### useMapContext()

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/MapProvider.md

Hook that returns the map context object containing width, height, projection, and path. Throws an error if used outside a MapProvider.

```APIDOC
## useMapContext()

### Description
Returns the map context object containing `width`, `height`, `projection`, and `path`. Throws an error if called outside a `MapProvider`.

### Signature
`useMapContext(): MapContextType`

### Returns
- **width** (number) - The width of the map.
- **height** (number) - The height of the map.
- **projection** (d3-geo projection) - The projection function.
- **path** (d3-geo path generator) - The path generator function.

### Throws
- `Error("useMapContext must be used within MapProvider")` when called outside a `MapProvider`.

### Example
```jsx
import { MapProvider, useMapContext } from "react-simple-maps"

const ProbedComponent = () => {
  const { width, height, projection, path } = useMapContext()
  const d = path({ type: "Point", coordinates: [4.8994, 52.3791] })
  return <path d={d} fill="tomato" /> // projected point
}

export const ManualMap = () => (
  <svg viewBox="0 0 800 600" className="rsm-svg">
    <MapProvider projection="geoEquirectangular" width={800} height={600}>
      <ProbedComponent />
    </MapProvider>
  </svg>
)
```
```

--------------------------------

### Marker with geoOrthographic projection handling null returns

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Marker.md

Demonstrates that with a geoOrthographic projection, markers on the far side of the globe project to null and the component renders nothing, avoiding crashes or stray SVG groups. The example includes a comment explaining this behavior.

```jsx
import { ComposableMap, Marker } from "react-simple-maps"

export const GlobeMarkers = () => (
  <ComposableMap projection="geoOrthographic" projectionConfig={{ scale: 280 }}>
    {/* Coordinates behind the globe: Marker silently renders null,
        so no crash and no stray SVG group. */}
    <Marker coordinates={[0, 0]}>
      <circle r={4} fill="tomato" />
    </Marker>
    <Marker coordinates={[160, 40]}>
      <circle r={4} fill="tomato" />
    </Marker>
  </ComposableMap>
)
```

--------------------------------

### Line component source code (src/core/components/Line.ts)

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/Line.md

The implementation of the Line component. It uses useMapContext to get the path generator, builds a LineString geometry from coordinates or from/to, and renders a path element with the generated d attribute. The component forwards rest props and applies default styles.

```tsx
// src/core/components/Line.ts (lines 5–37)
const Line = forwardRef<SVGPathElement, LineProps>(
  (
    {
      from = [0, 0],
      to = [0, 0],
      coordinates,
      stroke = "currentcolor",
      strokeWidth = 3,
      fill = "transparent",
      className = "",
      ...restProps
    },
    ref
  ) => {
    const { path } = useMapContext()

    const lineData = {
      type: "LineString" as const,
      coordinates: coordinates || [from, to],
    }

    return React.createElement("path", {
      ref,
      d: path(lineData),
      className: `rsm-line ${className}`,
      stroke,
      strokeWidth,
      fill,
      ...restProps,
    })
  }
)
```

--------------------------------

### Root entry — src/index.ts

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/api-reference/README.md

Re-exports the core and zoom modules from the root entry point.

```typescript
export * from "./core/index"
export * from "./zoom/index"
```

--------------------------------

### Catching useMapContext error with React error boundary

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/errors.md

This example shows how to catch the useMapContext error using a React error boundary. The MapBoundary component uses getDerivedStateFromError to set an error state and render a fallback. The Probe component calls useMapContext, which throws when misused, and the boundary catches it during render.

```TSX
import { useMapContext } from "react-simple-maps"

class MapBoundary extends React.Component {
  state = { hasError: false }
  static getDerivedStateFromError() {
    return { hasError: true }
  }
  render() {
    return this.state.hasError ? <div>Map provider missing</div> : this.props.children
  }
}

function Probe() {
  const { projection } = useMapContext() // throws here when misused
  return null
}

export const App = () => (
  <MapBoundary>
    <Probe /> {/* renders the boundary fallback instead of crashing */}
  </MapBoundary>
)
```

--------------------------------

### Safe usage of useZoomPanContext with ZoomPanProvider

Source: https://github.com/zcreativelabs/react-simple-maps/blob/main/_autodocs/errors.md

Shows how to wrap a component using useZoomPanContext inside a ZoomPanProvider to avoid the error. The provider supplies a value with x, y, k, and transformString. This is the recommended pattern for using the hook directly.

```TSX
import { ZoomPanProvider, useZoomPanContext } from "react-simple-maps"

const Label = () => {
  const { transformString } = useZoomPanContext()
  return <div>{transformString}</div>
}

export const Safe = () => (
  <ZoomPanProvider value={{ x: 0, y: 0, k: 1, transformString: "translate(0 0) scale(1)" }}>
    <Label />
  </ZoomPanProvider>
)
```
Tokens:
Raw