Using React

To quickly spin up a React project with the essentials, click here to fork the Mappedin React Template on CodeSandbox. This template already contains the useVenue and useMapView hooks.

For building locally, start by adding initializing a React app and adding @mappedin/mappedin-js.

npx create-react-app mappedin-react-app --template typescript
cd mappedin-react-app
yarn add @mappedin/mappedin-js

The Mappedin Web SDK does not provide React components. You will need to use effects to fetch the data and display it within your app. There are many ways you could achieve this depending on your project setup, but in this guide we'll illustrate writing a few custom React hooks.


Create a new hook called useVenue. The useVenue hook asynchronously fetches the Mappedin data using getVenue. It takes the venue options as a parameter and returns a Mappedin venue object which we pass to useMapView.

function useVenue(options: TGetVenueOptions) {
// Store the venue object in a state variable
const [venue, setVenue] = useState<Mappedin | undefined>();
// Fetch data asynchronously whenever options are changed
useEffect(() => {
let ignore = false;
const fetchData = async () => {
try {
const data = await getVenue(options);
// Update state variable after data is fetched
if (!ignore) {
} catch (e) {
// Handle error
return () => {
ignore = true;
}, [options]);
// Return the venue object
return venue;


Create another hook called useMapView. The useMapView hook calls showVenue to render the MapView on an element. It takes an HTMLElement and the venue object returned from useVenue as required parameters. It returns the MapView instance which you can use to manipulate the map.

You can read about the other options you can pass to useMapView in the TShowVenueOptions section of the API Reference.

function useMapView(
el: HTMLElement | null,
venue: Mappedin | undefined,
options?: TShowVenueOptions
) {
// Store the MapView instance in a state variable
const [mapView, setMapView] = useState<MapView | undefined>();
// Render the MapView asynchronously
useEffect(() => {
const renderVenue = async () => {
// Do nothing if the map container or venue data are not initialized
if (el == null || venue == null) {
// Do nothing if the mapView is already rendered with the current venue data
if (mapView != null && mapView.venue.venue.id === venue.venue.id) {
// If the mapView has been rendered with old data, destroy it
if (mapView != null) {
// Try to render the mapView
try {
const _mapView = await showVenue(el, venue, options);
} catch (e) {
// Handle error
}, [el, venue, options, mapView]);
// Return the MapView instance
return mapView;


Using these two custom hooks we can attach a MapView instance to an element in our React component.

// See Trial API key Terms and Conditions
// https://developer.mappedin.com/guides/api-keys
const options: TGetVenueOptions = {
venue: "mappedin-demo-mall",
clientId: "5eab30aa91b055001a68e996",
clientSecret: "RJyRXKcryCMy4erZqqCbuB1NbR66QTGNXVE0x3Pg6oCIlUR1",
export default function App() {
const mapRef = useRef<HTMLDivElement | null>(null);
const venue = useVenue(options);
const mapView = useMapView(mapRef.current, venue);
return <div id="app" ref={mapRef} />;

You should now see a rendering of the Mappedin Demo Mall in your React app, like the CodeSandbox example below.

Other Useful Hooks

The above hooks should help you get the basic MapView instance up and running, which you can then use to add interactivity or floating labels to your map. Depending on your needs, you may wish to create additional hooks to handle these map interactions as well.

We've provided code snippets for some supplementary hooks that can help to get you started.


useMapClick subscribes to the E_SDK_EVENT.CLICK event. It will fire the passed onClick function when the MapView detects a click event.

function useMapClick(
mapView: MapView | undefined,
onClick: (payload: E_SDK_EVENT_PAYLOAD[E_SDK_EVENT.CLICK]) => void
) {
const handleClick = useCallback(
// Subscribe to E_SDK_EVENT.CLICK
useEffect(() => {
if (mapView == null) {
mapView.on(E_SDK_EVENT.CLICK, handleClick);
// Cleanup
return () => {
mapView.off(E_SDK_EVENT.CLICK, handleClick);
}, [mapView, handleClick]);

You can read more about click events in the Adding Interactivity guide.


useOfflineSearch creates or reuses an OfflineSearch instance and passes it a new query all within one hook. It uses a new hook introduced in React 18, useDeferredValue, to improve performance by ensuring state updates are completed before performing another search.

function useOfflineSearch(venue: Mappedin | undefined, query: string) {
// Store the OfflineSearch instance in a state variable
const [searchInstance, setSearchInstance] = useState<
OfflineSearch | undefined
// Store the most recent results
const [results, setResults] = useState<TMappedinOfflineSearchResult[]>([]);
// Defer the new search query until state updates are complete
const deferredQuery = useDeferredValue(query);
// Create the OfflineSearch instance
useEffect(() => {
if (venue == null) {
const instance = new OfflineSearch(venue);
}, [venue]);
// Get search results asynchronously
useEffect(() => {
if (venue == null || searchInstance == null || deferredQuery === "") {
const generateSearchResults = async () => {
const results = await searchInstance.search(deferredQuery);
}, [deferredQuery, venue, searchInstance]);
// Return the most recent results
return results;

When using the useOfflineSearch hook, be sure to memoize the results to apply the useDeferredValue optimization to your component.

const results = useOfflineSearch(venue, searchQuery);
const searchResults = useMemo(
() =>
.filter((result) => result.type === "MappedinLocation")
.map((result) => (
key={(result.object as MappedinLocation).name}
onClick={() => {
setSelectedLocation(result.object as MappedinLocation);

You can read more about Mappedin's built-in search in the Search guide.


With additional hooks in place, we can build a performant interactive map experience in our React app. Try clicking on or searching for a location in the sandbox below, or browse the code to see how we put it all together.

Was this page helpful?

Next Topic

Using Angular