@geolonia/maps-react

React component wrapper for Geolonia Maps. Provides declarative React components built on @geolonia/maps-core.

Install

npm install @geolonia/maps-react maplibre-gl

Peer dependencies: react >= 18, react-dom >= 18, maplibre-gl >= 5

Usage

import 'maplibre-gl/dist/maplibre-gl.css';
import '@geolonia/maps-core/css';
import { Map, Marker, Source, Layer } from '@geolonia/maps-react';

function App() {
  return (
    <Map
      style="https://tile.openstreetmap.jp/styles/osm-bright/style.json"
      center={[139.7671, 35.6812]}
      zoom={14}
      containerStyle={{ width: '100%', height: '400px' }}
    >
      <Marker lat={35.6812} lng={139.7671} color="#E4402F">
        <p>Tokyo Station</p>
      </Marker>

      <Source id="stations" type="geojson" data={geojson}>
        <Layer
          id="stations-circle"
          type="circle"
          paint={{ 'circle-radius': 6, 'circle-color': '#007cbf' }}
        />
      </Source>
    </Map>
  );
}

Components

<Map>

Root component. Creates a Geolonia map instance and provides it to children via MapContext.

| Prop | Type | Description | |------|------|-------------| | apiKey | string | Geolonia API key | | style | string | Map style name or URL (e.g. "geolonia/basic-v2") | | center | [number, number] | Initial center [lng, lat] | | zoom | number | Initial zoom level | | bearing | number | Initial bearing (rotation) | | pitch | number | Initial pitch (tilt) | | hash | boolean | Sync map position with URL hash | | lang | 'ja' \| 'en' \| 'auto' | Language for style labels | | marker | boolean | Show default marker at center | | markerColor | string | Default marker color | | navigationControl | boolean \| ControlPosition | Navigation control | | geolocateControl | boolean \| ControlPosition | Geolocate button | | fullscreenControl | boolean \| ControlPosition | Fullscreen button | | scaleControl | boolean \| ControlPosition | Scale bar | | geoloniaControl | boolean \| ControlPosition | Geolonia logo | | minZoom / maxZoom | number | Zoom range | | gestureHandling | boolean | Gesture handling on scrollable pages | | loader | boolean | Loading animation | | 3d | boolean | Enable 3D mode | | className | string | CSS class for the container | | containerStyle | CSSProperties | Inline styles for the container | | onLoad | (map: GeoloniaMap) => void | Callback when map is loaded | | children | ReactNode | Child components | | ref | Ref<GeoloniaMap> | Ref to the map instance |

ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'

<Marker>

Displays a marker at the given coordinates. Children are rendered as a popup.

<Marker lat={35.6812} lng={139.7671} color="red">
  <p>Popup content</p>
</Marker>

| Prop | Type | Description | |------|------|-------------| | lat | number | Latitude (required) | | lng | number | Longitude (required) | | color | string | Marker color (changing recreates the marker) | | openPopup | boolean | Show the popup on mount / toggle open state when changed | | children | ReactNode | Popup content |

<Popup>

Displays a standalone popup at the given coordinates.

<Popup lat={35.6812} lng={139.7671} onClose={() => console.log('closed')}>
  <p>Content</p>
</Popup>

| Prop | Type | Description | |------|------|-------------| | lat | number | Latitude (required) | | lng | number | Longitude (required) | | onClose | () => void | Callback when popup is closed | | children | ReactNode | Popup content |

<Source> / <Layer>

Declaratively add MapLibre sources and layers. Nesting <Layer> inside <Source> automatically inherits the source ID.

<Source id="my-source" type="geojson" data={geojson}>
  <Layer
    id="my-layer"
    type="circle"
    paint={{ 'circle-radius': 6, 'circle-color': '#007cbf' }}
  />
</Source>

<Layer> props match LayerSpecification from MapLibre GL, plus beforeId for insertion order.

useMap()

Hook to access the map instance from MapContext. Must be used inside <Map>.

import { useMap } from '@geolonia/maps-react';

function ZoomDisplay() {
  const map = useMap();
  return <div>Zoom: {map.getZoom().toFixed(1)}</div>;
}

useSourceId()

Hook to access the parent <Source> ID from SourceContext. Useful for custom layer components.

Development

npm install
npm run build     # ESM + CJS + DTS
npm run test      # Vitest unit tests
npm run test:coverage # Vitest with coverage report
npm run e2e       # Playwright E2E tests
npm run lint      # Biome
npm run dev       # Vite dev server (example/)

License

MIT