OpenLayersMap

The OpenLayersMap component is the root container for all map functionality. It manages the OpenLayers map instance and provides context to child components.

Note: View-related props (center, zoom, etc.) have been moved to the MapView component. See the MapView section below for details.

Import

import { OpenLayersMap, MapView } from '@mixelburg/react-ol';

Props

onClick

• Type: (coordinate: Coordinates, event: MapBrowserEvent) => void
• Optional
• Description: Callback fired when the map is clicked

<OpenLayersMap
  onClick={(coord, event) => {
    console.log('Clicked at:', coord.lat, coord.long);
  }}
/>

wrapperProps

• Type: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>
• Optional
• Description: Props to pass to the wrapper div element (className, style, etc.)

<OpenLayersMap
  wrapperProps={{
    style: { width: '100%', height: '600px' },
    className: 'my-map-container'
  }}
/>

children

• Type: ReactNode
• Optional
• Description: Child components (layers, features, overlays)

Ref API

Access map methods using a ref created with useMapRef():

import { useMapRef } from '@mixelburg/react-ol';

const mapRef = useMapRef();

getMap()

• Returns: OLMap | null
• Description: Get the underlying OpenLayers Map instance

const olMap = mapRef.current?.getMap();

centerOn(coordinate, zoom?)

• Parameters:
  • coordinate: Coordinates - Target coordinates
  • zoom?: number - Optional zoom level
• Description: Center the map on specific coordinates

mapRef.current?.centerOn({ lat: 32.0853, long: 34.7818 }, 15);

getCenter()

• Returns: Coordinates | null
• Description: Get the current map center

const center = mapRef.current?.getCenter();
console.log(center?.lat, center?.long);

getZoom()

• Returns: number | null
• Description: Get the current zoom level

const zoom = mapRef.current?.getZoom();

setZoom(zoom)

• Parameters: zoom: number
• Description: Set the zoom level

mapRef.current?.setZoom(15);

fitToExtent(extent?)

• Parameters: extent?: number[] - Optional extent [minX, minY, maxX, maxY]
• Description: Fit the map to a specific extent

mapRef.current?.fitToExtent([minX, minY, maxX, maxY]);

fitAll(padding?)

• Parameters: padding?: number | number[] - Padding in pixels
• Description: Fit the map to show all features. Padding can be:
  • Single number: same padding on all sides
  • Array [top, right, bottom, left]

// Same padding on all sides
mapRef.current?.fitAll(20);

// Different padding per side
mapRef.current?.fitAll([20, 40, 20, 40]);

getLayers()

• Returns: MapLayersMap (Record of layer IDs to layer instances)
• Description: Get all map layers

const layers = mapRef.current?.getLayers();

Usage Examples

Uncontrolled Map

function MyMap() {
  return (
    <OpenLayersMap wrapperProps={{ style: { width: '100%', height: '500px' }}}>
      <MapView defaultCenter={{ lat: 32.0853, long: 34.7818 }} defaultZoom={13} />
      <MapTileLayer source={new OSM()} />
    </OpenLayersMap>
  );
}

Controlled Map with State

function MyMap() {
  const [center, setCenter] = useState({ lat: 32.0853, long: 34.7818 });
  const [zoom, setZoom] = useState(13);

  return (
    <div>
      <div>
        <button onClick={() => setZoom(zoom + 1)}>Zoom In</button>
        <button onClick={() => setZoom(zoom - 1)}>Zoom Out</button>
      </div>

      <OpenLayersMap wrapperProps={{ style: { width: '100%', height: '500px' }}}>
        <MapView
          center={center}
          onCenterChange={setCenter}
          zoom={zoom}
          onZoomChange={setZoom}
        />
        <MapTileLayer source={new OSM()} />
      </OpenLayersMap>
    </div>
  );
}

Using Map Ref

function MyMap() {
  const mapRef = useMapRef();

  const flyToLocation = () => {
    mapRef.current?.centerOn({ lat: 40.7128, long: -74.0060 }, 12);
  };

  const fitAllFeatures = () => {
    mapRef.current?.fitAll([50, 50, 50, 50]);
  };

  return (
    <div>
      <button onClick={flyToLocation}>Go to NYC</button>
      <button onClick={fitAllFeatures}>Fit All</button>

      <OpenLayersMap ref={mapRef}>
        <MapView defaultCenter={{ lat: 32.0853, long: 34.7818 }} defaultZoom={13} />
        {/* layers and features */}
      </OpenLayersMap>
    </div>
  );
}

MapView

The MapView component manages the map's viewport - its center position and zoom level. It must be used as a child of OpenLayersMap.

Import

import { MapView } from '@mixelburg/react-ol';

Props

defaultCenter

• Type: Coordinates ({ lat: number, long: number })
• Default: { lat: 0, long: 0 }
• Description: Initial center position of the map (uncontrolled mode)

<MapView defaultCenter={{ lat: 32.0853, long: 34.7818 }} />

defaultZoom

• Type: number
• Default: 8
• Description: Initial zoom level of the map (uncontrolled mode)

<MapView defaultZoom={13} />

center

• Type: Coordinates ({ lat: number, long: number })
• Optional
• Description: Current center position (controlled mode). When provided, the component becomes controlled.

const [center, setCenter] = useState({ lat: 32, long: 34 });
<MapView center={center} onCenterChange={setCenter} />

onCenterChange

• Type: (center: Coordinates) => void
• Optional
• Description: Callback fired when the map center changes (panning, dragging)

zoom

• Type: number
• Optional
• Description: Current zoom level (controlled mode). When provided, the component becomes controlled.

const [zoom, setZoom] = useState(13);
<MapView zoom={zoom} onZoomChange={setZoom} />

onZoomChange

• Type: (zoom: number) => void
• Optional
• Description: Callback fired when the zoom level changes

Notes

• The MapView component automatically handles coordinate transformation between lat/long (EPSG
  ) and Web Mercator (EPSG
  )
• In controlled mode, the component will update when center or zoom props change
• The component creates an OpenLayers View with projection "EPSG:3857" by default
• MapView must be a child of OpenLayersMap to function properly