API Reference

All parts of the component that you can use and combine to build your map.

<Map>
  <MapMarker coordinate={[lng, lat]}>
    <MarkerContent>
      <MarkerLabel />
    </MarkerContent>
    <MarkerPopup />
  </MapMarker>

  <MapRoute coordinates={...} />
  <MapControls />
  <MapUserLocation />
</Map>

The root container component that initializes MapLibre React Native and provides context to child components. Automatically handles theme switching between light and dark modes based on the device color scheme.

A hook that provides access to the MapLibre map and camera refs, plus loading state and theme. Must be used within a Map component.

const { mapRef, cameraRef, isLoaded, theme } = useMap();

// Access map instance
const center = await mapRef.current?.getCenter();

Returns an object with:

• mapRef - Ref to MapLibre MapView
• cameraRef - Ref to MapLibre Camera for programmatic movement
• isLoaded - Boolean indicating if map is loaded and ready
• theme - Current theme ("light" or "dark")

Renders map control buttons (zoom in/out and locate). Must be used inside Map.

A container for marker-related components. Provides context for its children and handles marker positioning.

Renders the visual content of a marker. Must be used inside MapMarker. If no children provided, renders a default blue dot marker.

Renders a popup (callout) attached to the marker that opens when the marker is pressed. Must be used inside MapMarker. Uses MapLibre's native Callout component.

Renders a text label above or below the marker. Must be used inside MarkerContent.

Renders a polyline on the map connecting coordinate points. Must be used inside Map. Drawn using native MapLibre layers for optimal performance.

Shows the user's current location on the map with automatic permission handling. Must be used inside Map.

A hook re-exported from MapLibre React Native that provides the user's current location.

import { useCurrentPosition } from "@/components/ui/map";

const position = useCurrentPosition();

// position contains:
// - coords: { longitude, latitude, altitude, accuracy, ... }
// - timestamp: number

For manual location permission handling, use expo-location directly. This is the recommended approach and is used internally by MapUserLocation.

import * as Location from "expo-location";
import { useEffect, useState } from "react";

function MyComponent() {
  const [hasPermission, setHasPermission] = useState(false);

  useEffect(() => {
    (async () => {
      // Request location permissions
      const { status } = await Location.requestForegroundPermissionsAsync();
      setHasPermission(status === "granted");
    })();
  }, []);

  // Get current position
  const getCurrentLocation = async () => {
    if (hasPermission) {
      const location = await Location.getCurrentPositionAsync({});
      console.log(location.coords.longitude, location.coords.latitude);
    }
  };

  return (
    <Map center={[-122.4194, 37.7749]} zoom={12}>
      {hasPermission && <MapUserLocation />}
    </Map>
  );
}

All components accept className string props for additional styling using Tailwind CSS classes (via NativeWind). This allows easy customization of layout, colors, spacing, and more using utility-first CSS directly in your JSX.