Skip to main content

useMapFirst Hook

The unified React hook for MapFirst SDK that provides all functionality in one place.

Import​

import { useMapFirst } from "@mapfirst/react";

Usage​

const {
  instance,
  state,
  setPrimaryType,
  setSelectedMarker,
  propertiesSearch,
  smartFilterSearch,
  boundsSearch,
  attachMapLibre,
  attachGoogle,
  attachMapbox,
} = useMapFirst(config);

Parameters​

config​

Configuration object for initializing MapFirst.

interface MapFirstConfig {
  adapter: any | null;
  initialLocationData?: {
    city?: string;
    country?: string;
    currency?: string;
  };
  environment?: "dev" | "prod";
  callbacks?: {
    onPropertiesChange?: (properties: Property[]) => void;
    onSelectedPropertyChange?: (id: number | null) => void;
    onBoundsChange?: (bounds: Bounds) => void;
    onSearchingStateChange?: (isSearching: boolean) => void;
    onError?: (error: Error) => void;
  };
}

Return Values​

instance​

The underlying MapFirstCore instance. Use this for advanced operations not covered by other methods.

instance: MapFirstCore | null;

state​

Current state of the MapFirst SDK.

interface MapFirstState {
  properties: Property[];
  selectedProperty: number | null;
  isSearching: boolean;
  bounds: Bounds | null;
  primaryType: "Accommodation" | "Restaurant" | "Attraction";
}

setPrimaryType​

Set the primary property type filter.

setPrimaryType: (type: 'Accommodation' | 'Restaurant' | 'Attraction') => void

Example:

setPrimaryType("Restaurant");

setSelectedMarker​

Select or deselect a property marker.

setSelectedMarker: (id: number | null) => void

Example:

// Select property with ID 12345
setSelectedMarker(12345);

// Deselect
setSelectedMarker(null);

propertiesSearch​

Search for properties by location and filters.

propertiesSearch: (params: SearchParams) => Promise<void>;

Parameters:

interface SearchParams {
  body: {
    city: string;
    country: string;
    filters?: {
      checkIn?: string; // ISO date format
      checkOut?: string; // ISO date format
      numAdults?: number;
      numChildren?: number;
      numRooms?: number;
      currency?: string;
      minPrice?: number;
      maxPrice?: number;
    };
  };
}

Example:

await propertiesSearch({
  body: {
    city: "Paris",
    country: "France",
    filters: {
      checkIn: "2024-06-01",
      checkOut: "2024-06-07",
      numAdults: 2,
      currency: "EUR",
    },
  },
});

smartFilterSearch​

Natural language search powered by AI.

smartFilterSearch: (params: SmartSearchParams) => Promise<void>;

Parameters:

interface SmartSearchParams {
  query: string;
  city?: string;
  country?: string;
}

Example:

await smartFilterSearch({
  query: "hotels near eiffel tower with pool",
  city: "Paris",
  country: "France",
});

boundsSearch​

Search properties within current map bounds.

boundsSearch: () => Promise<void>;

Example:

// Search visible area
await boundsSearch();

attachMapLibre​

Attach a MapLibre GL JS map.

attachMapLibre: (map: maplibregl.Map, options: AttachOptions) => void

Parameters:

interface AttachOptions {
  onMarkerClick?: (property: Property) => void;
  markerStyle?: MarkerStyle;
}

Example:

import maplibregl from "maplibre-gl";

const map = new maplibregl.Map({
  container: "map",
  style: "https://demotiles.maplibre.org/style.json",
  center: [2.3522, 48.8566],
  zoom: 12,
});

map.on("load", () => {
  attachMapLibre(map, {
    onMarkerClick: (property) => {
      console.log("Clicked:", property.name);
    },
  });
});

attachGoogle​

Attach a Google Maps instance.

attachGoogle: (map: google.maps.Map, options: AttachOptions) => void

Example:

const map = new google.maps.Map(document.getElementById("map"), {
  center: { lat: 48.8566, lng: 2.3522 },
  zoom: 12,
  mapId: "YOUR_MAP_ID",
});

attachGoogle(map, {
  onMarkerClick: (property) => {
    console.log("Clicked:", property.name);
  },
});

attachMapbox​

Attach a Mapbox GL JS map.

attachMapbox: (map: mapboxgl.Map, options: AttachOptions) => void

Example:

import mapboxgl from "mapbox-gl";

mapboxgl.accessToken = "YOUR_MAPBOX_TOKEN";

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v12",
  center: [2.3522, 48.8566],
  zoom: 12,
});

map.on("load", () => {
  attachMapbox(map, {
    onMarkerClick: (property) => {
      console.log("Clicked:", property.name);
    },
  });
});

Property Object​

interface Property {
  id: number;
  name: string;
  location: {
    lat: number;
    lng: number;
  };
  rating?: number;
  price?: number;
  currency?: string;
  type: "Accommodation" | "Restaurant" | "Attraction";
  address?: string;
  photos?: string[];
  amenities?: string[];
}

See Also​