@gmaps-kit/react/dist/index.d.mts

React components and hooks for Google Maps with gmaps-kit - useGeocoding, useDirections, usePlaces, useMarkers, useStreetView and more

import { MapInstance, PlacesClientOptions, PlacesClient, PlacesFindPlaceRequest, PlacesFindPlaceResponse, PlacesTextSearchRequest, PlacesTextSearchResponse, PlacesNearbySearchRequest, PlacesNearbySearchResponse, PlacesDetailsRequest, PlacesDetailsResponse, PlacesAutocompleteRequest, PlacesAutocompleteResponse, PlacesQueryAutocompleteRequest, PlacesQueryAutocompleteResponse, PlacesPhotoOptions, PlacesApiError, PlacesNewClientOptions, PlacesNewClient, PlacesNewTextSearchRequest, PlacesNewTextSearchResponse, PlacesNewNearbySearchRequest, PlacesNewNearbySearchResponse, PlacesNewPlaceDetailsRequest, PlacesNewPlaceDetailsResponse, PlacesNewAutocompleteRequest, PlacesNewAutocompleteResponse, PlacesNewPhotoRequest, PlacesNewPhotoResponse, PlacesNewApiError, GeocodingClientOptions, GeocodingClient, GeocodeRequest, GeocodingResponse, ReverseGeocodeRequest, GeocodingApiError, StreetViewOptions, StreetViewEventHandlers, StreetViewInstance, DistanceMatrixResult as DistanceMatrixResult$1, DistanceMatrixOptions } from '@gmaps-kit/core';
export * from '@gmaps-kit/core';
import React from 'react';

interface UseGoogleMapsOptions {
    apiKey: string;
    libraries?: string[];
    onLoad?: () => void;
    onError?: (error: Error) => void;
}
interface UseGoogleMapsReturn {
    isLoaded: boolean;
    isLoading: boolean;
    error: Error | null;
    load: () => Promise<void>;
}
declare function useGoogleMaps(options: UseGoogleMapsOptions): UseGoogleMapsReturn;

interface UseMapOptions {
    center?: google.maps.LatLngLiteral;
    zoom?: number;
    mapTypeId?: google.maps.MapTypeId;
    mapId?: string;
    onMapReady?: (map: MapInstance) => void;
}
interface UseMapReturn {
    mapInstance: MapInstance | null;
    isReady: boolean;
    center: google.maps.LatLngLiteral | null;
    zoom: number | null;
    setCenter: (center: google.maps.LatLngLiteral) => void;
    setZoom: (zoom: number) => void;
    panTo: (center: google.maps.LatLngLiteral, zoom?: number) => void;
    fitToMarkers: (markers: google.maps.Marker[]) => void;
}
declare function useMap(containerId: string, options?: UseMapOptions): UseMapReturn;

interface MarkerOptions {
    position: google.maps.LatLngLiteral;
    title?: string;
    content?: HTMLElement;
    draggable?: boolean;
    clickable?: boolean;
    zIndex?: number;
    onClick?: () => void;
    onDrag?: () => void;
    onDragEnd?: () => void;
}
interface UseMarkersReturn {
    markers: google.maps.marker.AdvancedMarkerElement[];
    addMarker: (options: MarkerOptions) => google.maps.marker.AdvancedMarkerElement;
    removeMarker: (marker: google.maps.marker.AdvancedMarkerElement) => void;
    updateMarker: (marker: google.maps.marker.AdvancedMarkerElement, options: Partial<MarkerOptions>) => void;
    clearAllMarkers: () => void;
    getMarkerPosition: (marker: google.maps.marker.AdvancedMarkerElement) => google.maps.LatLngLiteral | null;
}
declare function useMarkers(mapInstance: MapInstance | null): UseMarkersReturn;

interface GeocodingResult {
    address: string;
    location: google.maps.LatLngLiteral;
    placeId?: string;
}
interface UseGeocodingReturn {
    isLoading: boolean;
    error: Error | null;
    geocode: (address: string) => Promise<GeocodingResult[]>;
    geocodeFirst: (address: string) => Promise<GeocodingResult | null>;
    reverseGeocode: (location: google.maps.LatLngLiteral) => Promise<GeocodingResult[]>;
    reverseGeocodeFirst: (location: google.maps.LatLngLiteral) => Promise<GeocodingResult | null>;
    geocodeWithComponents: (address: string, components: google.maps.GeocoderComponentRestrictions) => Promise<GeocodingResult[]>;
    geocodeWithBounds: (address: string, bounds: google.maps.LatLngBounds) => Promise<GeocodingResult[]>;
    geocodeWithRegion: (address: string, region: string) => Promise<GeocodingResult[]>;
}
declare function useGeocoding(): UseGeocodingReturn;

type PlacesOperationName = 'findPlaceFromText' | 'textSearch' | 'nearbySearch' | 'placeDetails' | 'autocomplete' | 'queryAutocomplete' | 'textSearchNextPage' | 'nearbySearchNextPage';
interface UsePlacesOptions extends PlacesClientOptions {
}
interface UsePlacesReturn {
    client: PlacesClient;
    isLoading: boolean;
    error: Error | null;
    lastOperation: PlacesOperationName | null;
    findPlaceFromText: (request: PlacesFindPlaceRequest) => Promise<PlacesFindPlaceResponse>;
    textSearch: (request: PlacesTextSearchRequest) => Promise<PlacesTextSearchResponse>;
    nearbySearch: (request: PlacesNearbySearchRequest) => Promise<PlacesNearbySearchResponse>;
    placeDetails: (request: PlacesDetailsRequest) => Promise<PlacesDetailsResponse>;
    autocomplete: (request: PlacesAutocompleteRequest) => Promise<PlacesAutocompleteResponse>;
    queryAutocomplete: (request: PlacesQueryAutocompleteRequest) => Promise<PlacesQueryAutocompleteResponse>;
    textSearchNextPage: (pagetoken: string, delayMs?: number) => Promise<PlacesTextSearchResponse>;
    nearbySearchNextPage: (pagetoken: string, delayMs?: number) => Promise<PlacesNearbySearchResponse>;
    buildPhotoUrl: (photoReference: string, options?: PlacesPhotoOptions) => string;
}
/**
 * React hook that exposes a typed interface for the Google Places Web Service.
 * Consumers provide an API key and optionally a custom fetch implementation for server-side usage.
 */
declare function usePlaces(options: UsePlacesOptions): UsePlacesReturn;
type PlacesHookError = PlacesApiError;

type PlacesNewOperationName = 'textSearch' | 'nearbySearch' | 'placeDetails' | 'autocomplete' | 'getPhoto';
interface UsePlacesNewOptions extends PlacesNewClientOptions {
}
interface UsePlacesNewReturn {
    client: PlacesNewClient;
    isLoading: boolean;
    error: Error | null;
    lastOperation: PlacesNewOperationName | null;
    textSearch: (request: PlacesNewTextSearchRequest) => Promise<PlacesNewTextSearchResponse>;
    nearbySearch: (request: PlacesNewNearbySearchRequest) => Promise<PlacesNewNearbySearchResponse>;
    placeDetails: (request: PlacesNewPlaceDetailsRequest) => Promise<PlacesNewPlaceDetailsResponse>;
    autocomplete: (request: PlacesNewAutocompleteRequest) => Promise<PlacesNewAutocompleteResponse>;
    getPhoto: (request: PlacesNewPhotoRequest) => Promise<PlacesNewPhotoResponse>;
    buildPhotoUrl: (photoName: string, options?: {
        maxWidthPx?: number;
        maxHeightPx?: number;
    }) => string;
}
/**
 * React hook that exposes a typed interface for the Google Places API (New).
 * This hook provides better CORS support and modern API features compared to the legacy Places API.
 * Consumers provide an API key and optionally a custom fetch implementation for server-side usage.
 */
declare function usePlacesNew(options: UsePlacesNewOptions): UsePlacesNewReturn;
type PlacesNewHookError = PlacesNewApiError;

type GeocodingOperation = 'geocode' | 'reverseGeocode';
interface UseGeocodingServiceOptions extends GeocodingClientOptions {
}
interface UseGeocodingServiceReturn {
    client: GeocodingClient;
    isLoading: boolean;
    error: Error | null;
    lastOperation: GeocodingOperation | null;
    geocode: (request: GeocodeRequest) => Promise<GeocodingResponse>;
    reverseGeocode: (request: ReverseGeocodeRequest) => Promise<GeocodingResponse>;
}
declare function useGeocodingService(options: UseGeocodingServiceOptions): UseGeocodingServiceReturn;
type GeocodingServiceHookError = GeocodingApiError;

interface UseStreetViewOptions extends StreetViewOptions {
    eventHandlers?: StreetViewEventHandlers;
}
interface UseStreetViewReturn {
    instance: StreetViewInstance | null;
    isReady: boolean;
    setPosition: (position: google.maps.LatLngLiteral) => void;
    getPosition: () => google.maps.LatLngLiteral | null;
    setPov: (pov: google.maps.StreetViewPov) => void;
    getPov: () => google.maps.StreetViewPov | null;
    setVisible: (visible: boolean) => void;
    isVisible: () => boolean;
}
declare function useStreetView(containerId: string, options?: UseStreetViewOptions): UseStreetViewReturn;

interface BicyclingOptions {
    map?: google.maps.Map;
    autoRefresh?: boolean;
    autoRefreshInterval?: number;
}
interface UseBicyclingReturn {
    isLoading: boolean;
    error: Error | null;
    bicyclingLayer: google.maps.BicyclingLayer | null;
    isVisible: boolean;
    createBicyclingLayer: (options?: BicyclingOptions) => google.maps.BicyclingLayer;
    showBicycling: () => void;
    hideBicycling: () => void;
    toggleBicycling: () => void;
    refreshBicycling: () => void;
    removeBicyclingLayer: () => void;
}
declare function useBicycling(): UseBicyclingReturn;

declare global {
    namespace google.maps {
        interface MarkerClustererOptions {
            gridSize?: number;
            maxZoom?: number;
            minimumClusterSize?: number;
            averageCenter?: boolean;
            ignoreHidden?: boolean;
            enableRetinaIcons?: boolean;
            styles?: ClusterIconStyle[];
            imagePath?: string;
            imageExtension?: string;
            zoomOnClick?: boolean;
        }
        interface ClusterIconStyle {
            url: string;
            height: number;
            width: number;
            anchor?: number[] | google.maps.Point;
            textColor?: string;
            textSize?: number;
            backgroundPosition?: string;
        }
        class MarkerClusterer {
            constructor(map: google.maps.Map, markers?: google.maps.Marker[], options?: MarkerClustererOptions);
            addMarker(marker: google.maps.Marker): void;
            addMarkers(markers: google.maps.Marker[]): void;
            removeMarker(marker: google.maps.Marker): void;
            removeMarkers(markers: google.maps.Marker[]): void;
            clearMarkers(): void;
            redraw(): void;
            getMarkers(): google.maps.Marker[];
            getTotalMarkers(): number;
            getTotalClusters(): number;
        }
    }
}
interface ClusterOptions {
    gridSize?: number;
    maxZoom?: number;
    minimumClusterSize?: number;
    averageCenter?: boolean;
    ignoreHidden?: boolean;
    enableRetinaIcons?: boolean;
    styles?: google.maps.ClusterIconStyle[];
    imagePath?: string;
    imageExtension?: string;
    zoomOnClick?: boolean;
}
interface ClusterMarker {
    position: google.maps.LatLngLiteral;
    title?: string;
    data?: any;
}
interface UseClusteringReturn {
    clusterer: google.maps.MarkerClusterer | null;
    isReady: boolean;
    createClusterer: (mapInstance: MapInstance, markers: google.maps.Marker[], options?: ClusterOptions) => google.maps.MarkerClusterer;
    addMarkersToCluster: (markers: google.maps.Marker[]) => void;
    removeMarkersFromCluster: (markers: google.maps.Marker[]) => void;
    clearCluster: () => void;
    redrawCluster: () => void;
    getClusterer: () => google.maps.MarkerClusterer | null;
    getTotalMarkers: () => number;
    getTotalClusters: () => number;
    getMarkers: () => google.maps.Marker[];
}
/**
 * Check if MarkerClusterer library is loaded
 */
declare function isMarkerClustererLoaded(): boolean;
declare function useClustering(): UseClusteringReturn;

interface DirectionsRequest {
    origin: string | google.maps.LatLngLiteral;
    destination: string | google.maps.LatLngLiteral;
    travelMode?: google.maps.TravelMode;
    waypoints?: google.maps.DirectionsWaypoint[];
    optimizeWaypoints?: boolean;
    avoidHighways?: boolean;
    avoidTolls?: boolean;
    region?: string;
}
interface DirectionsResult {
    directions: google.maps.DirectionsResult | null;
    distance: number;
    duration: number;
    bounds: google.maps.LatLngBounds | null;
    renderer: google.maps.DirectionsRenderer | null;
}
interface UseDirectionsReturn {
    isLoading: boolean;
    error: Error | null;
    result: DirectionsResult | null;
    getDirections: (request: DirectionsRequest) => Promise<DirectionsResult>;
    renderDirections: (mapInstance: MapInstance) => void;
    clearDirectionsFromMap: () => void;
    fitMapToRoute: (mapInstance: MapInstance) => void;
}
declare function useDirections(): UseDirectionsReturn;

interface DistanceMatrixRequest extends DistanceMatrixOptions {
}
interface DistanceMatrixResult {
    results: DistanceMatrixResult$1[];
    origins: (string | google.maps.LatLngLiteral)[];
    destinations: (string | google.maps.LatLngLiteral)[];
    service: google.maps.DistanceMatrixService | null;
}
interface UseDistanceMatrixReturn {
    isLoading: boolean;
    error: Error | null;
    result: DistanceMatrixResult | null;
    getDistanceMatrix: (request: DistanceMatrixRequest) => Promise<DistanceMatrixResult>;
    createService: (mapInstance: MapInstance) => google.maps.DistanceMatrixService;
}
declare function useDistanceMatrix(): UseDistanceMatrixReturn;

interface ElevationRequest {
    locations: google.maps.LatLngLiteral[] | google.maps.LatLng[];
    path?: google.maps.LatLngLiteral[] | google.maps.LatLng[];
    samples?: number;
}
interface ElevationResult {
    elevation: number;
    resolution: number;
    location: google.maps.LatLngLiteral;
}
interface UseElevationReturn {
    isLoading: boolean;
    error: Error | null;
    results: ElevationResult[] | null;
    getElevationForLocations: (request: ElevationRequest) => Promise<ElevationResult[]>;
    getElevationAlongPath: (request: ElevationRequest) => Promise<ElevationResult[]>;
    createElevationService: () => google.maps.ElevationService;
}
declare function useElevation(): UseElevationReturn;

interface GeometryCalculation {
    distance: number;
    bearing: number;
    heading: number;
    area: number;
    perimeter: number;
}
interface UseGeometryReturn {
    isLoading: boolean;
    error: Error | null;
    results: GeometryCalculation | null;
    computeDistanceBetween: (from: google.maps.LatLngLiteral, to: google.maps.LatLngLiteral) => number;
    computeHeading: (from: google.maps.LatLngLiteral, to: google.maps.LatLngLiteral) => number;
    computeOffset: (from: google.maps.LatLngLiteral, distance: number, heading: number) => google.maps.LatLngLiteral;
    computeOffsetOrigin: (to: google.maps.LatLngLiteral, distance: number, heading: number) => google.maps.LatLngLiteral;
    computeLength: (path: google.maps.LatLngLiteral[]) => number;
    computeArea: (path: google.maps.LatLngLiteral[]) => number;
    computeBounds: (path: google.maps.LatLngLiteral[]) => google.maps.LatLngBounds;
    computeCenter: (path: google.maps.LatLngLiteral[]) => google.maps.LatLngLiteral;
    isLocationOnEdge: (point: google.maps.LatLngLiteral, polyline: google.maps.LatLngLiteral[], tolerance?: number) => boolean;
    encodePath: (path: google.maps.LatLngLiteral[]) => string;
    decodePath: (encodedPath: string) => google.maps.LatLngLiteral[];
    spherical: typeof google.maps.geometry.spherical;
    encoding: typeof google.maps.geometry.encoding;
    poly: typeof google.maps.geometry.poly;
}
declare function useGeometry(): UseGeometryReturn;

interface HeatmapData {
    location: google.maps.LatLngLiteral;
    weight?: number;
}
interface HeatmapOptions {
    data: HeatmapData[];
    map?: google.maps.Map;
    radius?: number;
    opacity?: number;
    maxIntensity?: number;
    gradient?: string[];
    dissipating?: boolean;
}
interface UseHeatmapReturn {
    isLoading: boolean;
    error: Error | null;
    heatmapLayer: google.maps.visualization.HeatmapLayer | null;
    createHeatmap: (options: HeatmapOptions) => google.maps.visualization.HeatmapLayer;
    updateHeatmapData: (data: HeatmapData[]) => void;
    setHeatmapOptions: (options: Partial<HeatmapOptions>) => void;
    showHeatmap: (map?: google.maps.Map) => void;
    hideHeatmap: () => void;
    removeHeatmap: () => void;
}
declare function useHeatmap(): UseHeatmapReturn;

interface InfoWindowOptions {
    content: string | HTMLElement;
    position?: google.maps.LatLngLiteral;
    maxWidth?: number;
    pixelOffset?: google.maps.Size;
    zIndex?: number;
}
interface InfoWindowInstance {
    infoWindow: google.maps.InfoWindow;
    id: string;
    isOpen: boolean;
    content: string | HTMLElement;
    position?: google.maps.LatLngLiteral;
}
interface UseInfoWindowsReturn {
    infoWindows: InfoWindowInstance[];
    activeInfoWindow: InfoWindowInstance | null;
    createInfoWindowInstance: (options: InfoWindowOptions) => InfoWindowInstance;
    openInfoWindowInstance: (infoWindow: InfoWindowInstance, marker?: google.maps.marker.AdvancedMarkerElement, mapInstance?: MapInstance) => void;
    closeInfoWindowInstance: (infoWindow: InfoWindowInstance) => void;
    closeAllInfoWindows: () => void;
    updateInfoWindowContent: (infoWindow: InfoWindowInstance, content: string | HTMLElement) => void;
    removeInfoWindow: (infoWindow: InfoWindowInstance) => void;
}
declare function useInfoWindows(): UseInfoWindowsReturn;

interface MapEventHandlers {
    onClick?: (event: google.maps.MapMouseEvent) => void;
    onRightClick?: (event: google.maps.MapMouseEvent) => void;
    onDoubleClick?: (event: google.maps.MapMouseEvent) => void;
    onDrag?: () => void;
    onDragStart?: () => void;
    onDragEnd?: () => void;
    onZoomChanged?: () => void;
    onCenterChanged?: () => void;
    onBoundsChanged?: () => void;
    onIdle?: () => void;
    onTilesLoaded?: () => void;
    onHeadingChanged?: () => void;
    onTiltChanged?: () => void;
}
interface MapEventState {
    isDragging: boolean;
    isZooming: boolean;
    lastClickPosition: google.maps.LatLngLiteral | null;
    lastRightClickPosition: google.maps.LatLngLiteral | null;
    currentZoom: number | null;
    currentCenter: google.maps.LatLngLiteral | null;
    currentBounds: google.maps.LatLngBounds | null;
}
interface UseMapEventsReturn {
    eventState: MapEventState;
    addEventListeners: (mapInstance: MapInstance, handlers: MapEventHandlers) => void;
    removeEventListeners: (mapInstance: MapInstance) => void;
    getCurrentMapState: (mapInstance: MapInstance) => MapEventState;
}
declare function useMapEvents(): UseMapEventsReturn;

interface MaxZoomRequest {
    location: google.maps.LatLngLiteral;
}
interface MaxZoomResult {
    maxZoom: number;
    location: google.maps.LatLngLiteral;
}
interface UseMaxZoomReturn {
    isLoading: boolean;
    error: Error | null;
    result: MaxZoomResult | null;
    getMaxZoom: (request: MaxZoomRequest) => Promise<MaxZoomResult>;
    createMaxZoomService: () => google.maps.MaxZoomService;
}
declare function useMaxZoom(): UseMaxZoomReturn;

interface TrafficOptions {
    map?: google.maps.Map;
    autoRefresh?: boolean;
    autoRefreshInterval?: number;
}
interface UseTrafficReturn {
    isLoading: boolean;
    error: Error | null;
    trafficLayer: google.maps.TrafficLayer | null;
    isVisible: boolean;
    createTrafficLayer: (options?: TrafficOptions) => google.maps.TrafficLayer;
    showTraffic: () => void;
    hideTraffic: () => void;
    toggleTraffic: () => void;
    refreshTraffic: () => void;
    removeTrafficLayer: () => void;
}
declare function useTraffic(): UseTrafficReturn;

interface TransitOptions {
    map?: google.maps.Map;
    autoRefresh?: boolean;
    autoRefreshInterval?: number;
}
interface UseTransitReturn {
    isLoading: boolean;
    error: Error | null;
    transitLayer: google.maps.TransitLayer | null;
    isVisible: boolean;
    createTransitLayer: (options?: TransitOptions) => google.maps.TransitLayer;
    showTransit: () => void;
    hideTransit: () => void;
    toggleTransit: () => void;
    refreshTransit: () => void;
    removeTransitLayer: () => void;
}
declare function useTransit(): UseTransitReturn;

interface MapProps extends UseMapOptions {
    id: string;
    className?: string;
    style?: React.CSSProperties;
    children?: React.ReactNode;
    onMapReady?: (map: MapInstance) => void;
}
declare const Map: React.FC<MapProps>;

interface MarkerProps extends MarkerOptions {
    mapInstance: MapInstance | null;
    onMarkerCreated?: (marker: google.maps.marker.AdvancedMarkerElement) => void;
}
declare const Marker: React.FC<MarkerProps>;

interface InfoWindowProps {
    mapInstance: MapInstance | null;
    marker?: google.maps.marker.AdvancedMarkerElement;
    content: string | React.ReactNode;
    position?: google.maps.LatLngLiteral;
    isOpen?: boolean;
    onClose?: () => void;
}
declare const InfoWindow: React.FC<InfoWindowProps>;

export { type BicyclingOptions, type ClusterMarker, type ClusterOptions, type DirectionsRequest, type DirectionsResult, type DistanceMatrixRequest, type DistanceMatrixResult, type ElevationRequest, type ElevationResult, type GeocodingResult, type GeocodingServiceHookError, type GeometryCalculation, type HeatmapData, type HeatmapOptions, InfoWindow, type InfoWindowOptions, type InfoWindowProps, Map, type MapEventHandlers, type MapEventState, type MapProps, Marker, type MarkerOptions, type MarkerProps, type MaxZoomRequest, type MaxZoomResult, type PlacesHookError, type PlacesNewHookError, type TrafficOptions, type TransitOptions, type UseBicyclingReturn, type UseClusteringReturn, type UseDirectionsReturn, type UseDistanceMatrixReturn, type UseElevationReturn, type UseGeocodingReturn, type UseGeocodingServiceOptions, type UseGeocodingServiceReturn, type UseGeometryReturn, type UseGoogleMapsOptions, type UseGoogleMapsReturn, type UseHeatmapReturn, type UseInfoWindowsReturn, type UseMapEventsReturn, type UseMapOptions, type UseMapReturn, type UseMarkersReturn, type UseMaxZoomReturn, type UsePlacesNewOptions, type UsePlacesNewReturn, type UsePlacesOptions, type UsePlacesReturn, type UseStreetViewOptions, type UseStreetViewReturn, type UseTrafficReturn, type UseTransitReturn, isMarkerClustererLoaded, useBicycling, useClustering, useDirections, useDistanceMatrix, useElevation, useGeocoding, useGeocodingService, useGeometry, useGoogleMaps, useHeatmap, useInfoWindows, useMap, useMapEvents, useMarkers, useMaxZoom, usePlaces, usePlacesNew, useStreetView, useTraffic, useTransit };