Geo

Amplify UI Geo is powered by Geo APIs and Amazon Location Service.

Quick Start

Prerequisites:

1. Install @aws-amplify/ui-react-geo and @aws-amplify/geo with npm or yarn. ( e.g. npm install @aws-amplify/ui-react-geo @aws-amplify/geo)
2. Create map resources by following the Amplify Geo documentation.

MapView

The MapView component adds an interactive map to your application.

MapView is fully integrated with the open source library react-map-gl v7 while using maplibre-gl-js as the map tile source. MapView is used as a replacement to react-map-gl's default map and supports the same functionality.

You can import the MapView component with related styles and use it in your Amplify application without any additional configuration.

import { Amplify } from 'aws-amplify';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

export default function BasicMap() {
  return <MapView />;
}

body {
  margin: 0;
}

Setting Initial Viewport

The map's initial viewport can be set with the initialViewState property:

import { Amplify } from 'aws-amplify';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

export default function InitialViewport() {
  return (
    <MapView
      initialViewState={{
        latitude: 37.8,
        longitude: -122.4,
        zoom: 14,
      }}
    />
  );
}

Usage with react-map-gl

Moving Marker

The Marker component from the react-map-gl library can have dynamic latitude and longitude properties to create a moving marker. The marker's position will reflect changes in latitude and longitude.

import { useState } from 'react';
import { Marker } from 'react-map-gl';
import { Amplify } from 'aws-amplify';
import { Button } from '@aws-amplify/ui-react';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react/styles.css';
import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

export default function MapWithMovingMarker() {
  const [{ latitude, longitude }, setMarkerLocation] = useState({
    latitude: 40,
    longitude: -100,
  });

  const updateMarker = () =>
    setMarkerLocation({ latitude: latitude + 5, longitude: longitude + 5 });

  return (
    <>
      <Button onClick={updateMarker}>Move Marker</Button>
      <MapView>
        <Marker latitude={latitude} longitude={longitude} />
      </MapView>
    </>
  );
}

Marker with Popup

The Popup component from the react-map-gl library can be used with a Marker to communicate information to a user when the marker is clicked. The offset property can be used to prevent the popup from overlapping the marker.

import { useState } from 'react';
import { Marker, Popup } from 'react-map-gl';
import { Amplify } from 'aws-amplify';
import { Heading, Text } from '@aws-amplify/ui-react';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react/styles.css';
import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

function MarkerWithPopup({ latitude, longitude }) {
  const [showPopup, setShowPopup] = useState(false);

  const handleMarkerClick = ({ originalEvent }) => {
    originalEvent.stopPropagation();
    setShowPopup(true);
  };

  return (
    <>
      <Marker
        latitude={latitude}
        longitude={longitude}
        onClick={handleMarkerClick}
      />
      {showPopup && (
        <Popup
          latitude={latitude}
          longitude={longitude}
          offset={{ bottom: [0, -40] }}
          onClose={() => setShowPopup(false)}
        >
          <Heading level={2}>Marker Information</Heading>
          <Text>Some information about a location.</Text>
        </Popup>
      )}
    </>
  );
}

export default function MapWithMarkerPopup() {
  return (
    <MapView initialViewState={{ latitude: 40, longitude: -100, zoom: 3.5 }}>
      <MarkerWithPopup latitude={40} longitude={-100} />
    </MapView>
  );
}

Note: Ensure originalEvent.stopPropagation() is called in the marker click handler. This allows the showPopup state to be handled by the component.

Animation and Native Map Methods

You may want to access the native maplibre-gl map object from within the component that renders <MapView> (to animate a viewport transition with flyTo, for example). To accomplish this, you can pass your own ref to <MapView> using React's useRef hook which will contain the map object:

import { useCallback, useRef } from 'react';
import type { MapRef } from 'react-map-gl';
import { Amplify } from 'aws-amplify';
import { Button } from '@aws-amplify/ui-react';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react/styles.css';
import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

export default function MapWithRef() {
  const mapRef = useRef<MapRef>();

  const flyToMordor = useCallback(() => {
    mapRef.current.flyTo({ center: [172.78, -42.28], zoom: 5 });
  }, []);

  return (
    <>
      <Button onClick={flyToMordor}>Fly, you fools!</Button>
      <MapView ref={mapRef} />
    </>
  );
}

If you want access to the map object in a child component of <MapView>, you can use the useMap hook from react-map-gl instead:

import { useMap } from 'react-map-gl';
import { Amplify } from 'aws-amplify';
import { Button } from '@aws-amplify/ui-react';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react/styles.css';
import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';
import './styles.css';

Amplify.configure(awsExports);

function FlyToButton() {
  const { current: map } = useMap();

  const flyToMordor = () => {
    map.flyTo({ center: [172.78, -42.28], zoom: 5 });
  };

  return <Button onClick={flyToMordor}>Fly, you fools!</Button>;
}

export default function MapWithButton() {
  return (
    <MapView>
      <FlyToButton />
    </MapView>
  );
}

Location Search

LocationSearch provides location search powered by Amazon Location Service for the MapView component, using the viewport as the proximity for generating results. LocationSearch is used as a child component of MapView for which it renders visual markers and information based on its location search results.

You can import the LocationSearch component with related styles and use it as a child of MapView without any additional configuration.

import { useMap } from 'react-map-gl';
import { Amplify } from 'aws-amplify';
import { Button } from '@aws-amplify/ui-react';
import { MapView } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react/styles.css';
import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';
import './styles.css';

Amplify.configure(awsExports);

function FlyToButton() {
  const { current: map } = useMap();

  const flyToMordor = () => {
    map.flyTo({ center: [172.78, -42.28], zoom: 5 });
  };

  return <Button onClick={flyToMordor}>Fly, you fools!</Button>;
}

export default function MapWithButton() {
  return (
    <MapView>
      <FlyToButton />
    </MapView>
  );
}

LocationSearch Position

LocationSearch can be provided a position property when used with MapView. The property is not reactive, meaning the position is fixed after the component mounts. Valid values are 'top-right', 'top-left', 'bottom-right', and 'bottom-left'. Default value is 'top-right'.

import { Amplify } from 'aws-amplify';
import { MapView, LocationSearch } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);
export default function LocationSearchPosition() {
  return (
    <MapView>
      <LocationSearch position="top-left" />
    </MapView>
  );
}

Standalone LocationSearch

LocationSearch can also be used as a standalone component without MapView. As a standalone component, LocationSearch provides search results based on an initial proximity. When used as a standlone component, the proximity property with provided latitude and longitude properties is required.

import { Amplify } from 'aws-amplify';
import { LocationSearch } from '@aws-amplify/ui-react-geo';

import '@aws-amplify/ui-react-geo/styles.css';

import awsExports from './aws-exports';

Amplify.configure(awsExports);

const SAN_FRANCISCO = {
  latitude: 37.774,
  longitude: -122.431,
};

export default function StandaloneLocationSearch() {
  return <LocationSearch proximity={SAN_FRANCISCO} />;
}