Introduction to the React Native OMH Maps Library

Authors

Diego Zuluaga

Director of Solutions

Futurewei

Navigating the intricacies of mobile application development can be daunting, particularly when integrating map functionalities. However, the React Native OMH Maps library simplifies this process, offering a robust solution for embedding maps within your React Native applications. This library is part of the Open Mobile Hub (OMH) ecosystem, designed to enhance the user experience through seamless integration of mapping features.

‍

image of a broken app showing a missing map — Maps showing “OMH Maps demo won’t run without Google Play services, which are not supported by your device”

Overview and Benefits

The React Native OMH Maps library provides developers with a comprehensive toolkit for integrating map functionalities into React Native applications. Here are some of the key benefits:

Cross-Platform Compatibility: The library supports both iOS and Android platforms, ensuring a consistent user experience across different devices, including those with Google Mobile Services (GMS) and those without (non-GMS). This means it works on a variety of devices such as Pixel, Samsung, FireOS, Windows Subsystem for Android, EMUI and HarmonyOS (Android for Huawei devices), and any AOSP distribution without GMS.
Ease of Use: With a straightforward API, developers can quickly add maps to their applications without needing extensive knowledge of native code.
Customization: It offers extensive customization options, allowing developers to tailor the maps to their specific needs.
Performance: Built with performance in mind, the library ensures smooth and responsive map interactions, enhancing the overall user experience.

Supported Map Providers

The React Native OMH Maps library supports multiple map providers, making it versatile and adaptable to various needs. Here's a quick overview of the supported providers:

Use Case: Building a Cross-Platform Mapping App

In this guide, we'll walk you through the process of creating an application with mapping capabilities that work seamlessly on both GMS and non-GMS devices. This includes devices like Pixel, Samsung (GMS), and FireOS, Windows Subsystem for Android, EMUI, and HarmonyOS (non-GMS).

Step-by-Step Guide to Using React Native OMH Maps

Prerequisites

Before you begin, ensure you have the following installed:

Node.js
React Native CLI
A React Native project set up

Step 1: Install the Library

First, you need to install the React Native OMH Maps library. Open your terminal and navigate to your React Native project directory, then run:

^{npm install react-native-omh-maps}

Or if you prefer using Yarn:

^{yarn add react-native-omh-maps}

Step 2: Link the Library

For React Native versions below 0.60, you need to link the library manually:

^{react-native link react-native-omh-maps}

For React Native 0.60 and above, the library should be linked automatically.

Step 3: Configure Permissions

For Android, you need to configure the necessary permissions in your ^{AndroidManifest.xml} file:

  
          <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
        
          <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

view raw AndroidManifest.xml hosted with ❤ by GitHub

For iOS, open your ^Info.plist and add the following keys:

  
          <key>NSLocationWhenInUseUsageDescription</key>
        
          <string>We need your location to show you relevant information.</string>
        
          <key>NSLocationAlwaysUsageDescription</key>
        
          <string>We need your location to show you relevant information.</string>

view raw Info.xml hosted with ❤ by GitHub

Step 4: Initialize the Maps Module

Before interacting with any maps plugin, it is necessary to initialize the maps module. Import the necessary components and initialize the module as shown below:

  
          import { OmhMapView, OmhMapsModule, OmhMapsGoogleMapsIOSProvider } from '@openmobilehub/maps-core';
        
          import { OmhMapsGoogleMapsProvider } from '@openmobilehub/maps-plugin-googlemaps';
        
          import { OmhMapsOpenStreetMapProvider } from '@openmobilehub/maps-plugin-openstreetmap';

view raw info plist.jsx hosted with ❤ by GitHub

Note: You can use different providers for iOS and Android. For Android, you can use different providers for devices with and without Google Play Services. Remember to initialize the module before using any of its components.

  
          OmhMapsModule.initialize({
        
            gmsProvider: OmhMapsGoogleMapsProvider,
        
            nonGmsProvider: OmhMapsOpenStreetMapProvider, // Note: Google Maps is not available on devices without Google Play Services.
        
            iosProvider: OmhMapsGoogleMapsIOSProvider,
        
          });

view raw maps module.jsx hosted with ❤ by GitHub

Step 5: Import and Use the Map Component

Now, you can import the map component into your React Native project and use it. Here is a basic example:

  
          import React from 'react';
        
          import { StyleSheet, View } from 'react-native';
        
          import { OMHMapView } from 'react-native-omh-maps';
        
          const App = () => {
        
            return (
        
              <View style={styles.container}>
        
                <OMHMapView
        
                  style={styles.map}
        
                  initialRegion={{
        
                    latitude: 37.78825,
        
                    longitude: -122.4324,
        
                    latitudeDelta: 0.0922,
        
                    longitudeDelta: 0.0421,
        
                  }}
        
                />
        
              </View>
        
            );
        
          };
        
          const styles = StyleSheet.create({
        
            container: {
        
              ...StyleSheet.absoluteFillObject,
        
              justifyContent: 'flex-end',
        
              alignItems: 'center',
        
            },
        
            map: {
        
              ...StyleSheet.absoluteFillObject,
        
            },
        
          });
        
          export default App;

view raw MapComponent.jsx hosted with ❤ by GitHub

image of a successful app showcasing OMH maps

Step 6: Customizing the Map

You can customize the map by using various props provided by the ^OMHMapView component. Here are a few examples:

Markers

Add markers to your map to indicate specific locations.

  
          import { OMHMarker } from 'react-native-omh-maps';
        
          <OMHMapView
        
            style={styles.map}
        
            initialRegion={{
        
              latitude: 37.78825,
        
              longitude: -122.4324,
        
              latitudeDelta: 0.0922,
        
              longitudeDelta: 0.0421,
        
            }}
        
          >
        
            <OMHMarker
        
              coordinate={{ latitude: 37.78825, longitude: -122.4324 }}
        
              title="Marker Title"
        
              description="Marker Description"
        
            />
        
          </OMHMapView>

view raw OMHMapView.jsx hosted with ❤ by GitHub

Polylines

Draw polylines to show routes or boundaries.

  
          import { OMHPolyline } from 'react-native-omh-maps';
        
          <OMHMapView
        
            style={styles.map}
        
            initialRegion={{
        
              latitude: 37.78825,
        
              longitude: -122.4324,
        
              latitudeDelta: 0.0922,
        
              longitudeDelta: 0.0421,
        
            }}
        
          >
        
            <OMHPolyline
        
              coordinates={[
        
                { latitude: 37.78825, longitude: -122.4324 },
        
                { latitude: 37.78925, longitude: -122.4314 },
        
              ]}
        
              strokeColor="#000"
        
              strokeWidth={3}
        
            />
        
          </OMHMapView>

view raw Polylines.jsx hosted with ❤ by GitHub

Custom Map Styles

Apply custom styles to your map.

  
          const customMapStyle = [
        
            {
        
              elementType: 'geometry',
        
              stylers: [{ color: '#242f3e' }],
        
            },
        
            // Add more styles as needed
        
          ];
        
          <OMHMapView
        
            style={styles.map}
        
            customMapStyle={customMapStyle}
        
            initialRegion={{
        
              latitude: 37.78825,
        
              longitude: -122.4324,
        
              latitudeDelta: 0.0922,
        
              longitudeDelta: 0.0421,
        
            }}
        
          />

view raw MapStyles.jsx hosted with ❤ by GitHub

Try the Sample App

To see the finished product in action, you can try the sample app provided by OMH. This will give you a hands-on experience with the library's capabilities and features. Check out the sample app here.

Custom Plugins

The React Native OMH Maps library allows for extensive customization, including the ability to write custom plugins to support additional map providers. This flexibility ensures that the library can be adapted to meet the unique needs of various projects.

Android Native Support

OMH Maps also supports Android Native for apps built with Android View. This extends the library's flexibility and usability for developers working on native Android projects. For more information, check out the Android OMH Maps repository.

Conclusion

The React Native OMH Maps library is a powerful tool for integrating maps into your mobile applications, providing a seamless and customizable experience. By following the steps outlined above, you can quickly get started and begin leveraging this library's full potential in your React Native projects.

In the future, OMH aims to support more map providers and expand to more platforms like HarmonyOS Next and cross-platform frameworks like Flutter, meeting developers where they are. For more detailed information, refer to the official documentation. Happy coding!

Launching or scaling an open-source project?

We help teams bring new open-source projects to life and grow them within the React Native space.

Let’s chat

Insights

Learn more about Open Source

View all

Aug 7Article

Visualizing Open Source Licenses to Analyze Compliance and Reduce Legal Risk

Discover how license-kit visualize maps and analyzes your dependency graph, helping you spot license issues, duplicates, and restrictive packages with interactive views, stats, and AI-powered summaries.

Mar 26Podcast

How Definitely Typed Changed TypeScript Forever

Discover the story behind Definitely Typed with its creator, Boris Yankov, and learn how it became essential for type-safe JavaScript in the TypeScript ecosystem.

Oct 14Article

Introducing the OMH Cloud Storage Module

Discover the OMH Cloud Storage Module. This open-source solution simplifies cloud storage integration for React Native apps.

Apr 22Podcast

Behind the Scenes of React Native 0.74 Release

Join the release crew members to find out what new features and improvements React Native 0.74 brings to the cross-platform development world.

Apr 27Podcast

Callstack OSS Update

April 2023 Callstack OSS Update: RFC for Expo Config Plugins, Re.Pack & Paper news.

Dec 6Article

React Native Paper 5.0 - What’s New?

React Native Paper 5.0 is here! Dive into the latest updates and improvements.

Feb 8Article

Stripe React Native: the Most Common Questions - Tipsi Migration Guide, Part 5

Check out the list of the most common questions about Stripe react Native Library prepared by Jakub Kłobus, software engineer at Callstack.

Feb 6Article

Stripe React Native Migration Function by Function - Tipsi Migration Guide, Part 3

In the third part of the Tipsi Migration Guide we describe the Stripe React Native migration function by function.

Dec 6Article

Stripe React Native Configuration - Tipsi Migration Guide, Part 2

In the second part of the Tipsi Migration Guide by Callstack, you'll learn how to properly configure the stripe-react-native library.

Mar 19Tutorial

The Hard Way vs. The React Native AI SDK Way: Stop Writing Custom Modules for Every Model

Learn how React Native AI uses a unified provider model to switch between cloud and on-device LLMs without rewriting application logic, enabling reliable AI experiences online and offline.

Mar 12Tutorial

Build Smarter Apps: Tool Calling & AI Orchestration Explained

Learn how on-device models in React Native can call tools, interact with external APIs, and return structured outputs you can use directly in application logic.

Mar 5Tutorial

MLC LLM + React Native: On-Device AI Without the Pain

Learn how to run third-party on-device LLMs in React Native using MLC LLM. Choose your models, run them efficiently across platforms, and keep a unified JavaScript API with React Native AI.

Feb 24Tutorial

Intelligent Fallbacks with Apple Intelligence in React Native

Learn how to use Apple’s built-in Foundation Models in React Native apps, reduce memory usage, and enable fast, fully on-device AI with React Native AI Apple.

Feb 10Tutorial

What Is the React Native AI SDK? A Complete Intro & Quickstart

Learn why on-device AI matters for React Native apps, how local LLMs behave offline, and what problems React Native AI is designed to solve from day one.

Jan 29Tutorial

Implementing an Android TurboModule with Kotlin

Learn how to implement a React Native TurboModule on Android, from the TypeScript spec and Codegen to the Kotlin implementation and package registration.

Jan 19Tutorial

Working with Different Threads in Swift TurboModules

Learn how JavaScript, native module, background, and main threads interact in React Native TurboModules, and how to use GCD queues to run async work safely in Swift.

Jan 9Tutorial

How to Add Type-Safe Constants to Swift TurboModules

Learn how to expose typed, immutable constants from a Swift TurboModule using Codegen, and get full end-to-end type safety between native and JavaScript.

Dec 30Tutorial

Adding Event Emitters to Your TurboModule in Swift

Learn how to emit native events from a Swift TurboModule and subscribe to them in JavaScript, including proper memory management and Codegen integration.

Dec 22Tutorial

Writing Your First TurboModule in Swift

Learn how to build a fully working TurboModule in Swift, integrate it with Codegen, and bridge it through Objective‑C inside an Expo app.

	<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
	<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

	<key>NSLocationWhenInUseUsageDescription</key>
	<string>We need your location to show you relevant information.</string>
	<key>NSLocationAlwaysUsageDescription</key>
	<string>We need your location to show you relevant information.</string>

	import { OmhMapView, OmhMapsModule, OmhMapsGoogleMapsIOSProvider } from '@openmobilehub/maps-core';
	import { OmhMapsGoogleMapsProvider } from '@openmobilehub/maps-plugin-googlemaps';
	import { OmhMapsOpenStreetMapProvider } from '@openmobilehub/maps-plugin-openstreetmap';

	OmhMapsModule.initialize({
	gmsProvider: OmhMapsGoogleMapsProvider,
	nonGmsProvider: OmhMapsOpenStreetMapProvider, // Note: Google Maps is not available on devices without Google Play Services.
	iosProvider: OmhMapsGoogleMapsIOSProvider,
	});

	import React from 'react';
	import { StyleSheet, View } from 'react-native';
	import { OMHMapView } from 'react-native-omh-maps';

	const App = () => {
	return (
	<View style={styles.container}>
	<OMHMapView
	style={styles.map}
	initialRegion={{
	latitude: 37.78825,
	longitude: -122.4324,
	latitudeDelta: 0.0922,
	longitudeDelta: 0.0421,
	}}
	/>
	</View>
	);
	};

	const styles = StyleSheet.create({
	container: {
	...StyleSheet.absoluteFillObject,
	justifyContent: 'flex-end',
	alignItems: 'center',
	},
	map: {
	...StyleSheet.absoluteFillObject,
	},
	});

	export default App;

	import { OMHMarker } from 'react-native-omh-maps';

	<OMHMapView
	style={styles.map}
	initialRegion={{
	latitude: 37.78825,
	longitude: -122.4324,
	latitudeDelta: 0.0922,
	longitudeDelta: 0.0421,
	}}
	>
	<OMHMarker
	coordinate={{ latitude: 37.78825, longitude: -122.4324 }}
	title="Marker Title"
	description="Marker Description"
	/>
	</OMHMapView>

	import { OMHPolyline } from 'react-native-omh-maps';

	<OMHMapView
	style={styles.map}
	initialRegion={{
	latitude: 37.78825,
	longitude: -122.4324,
	latitudeDelta: 0.0922,
	longitudeDelta: 0.0421,
	}}
	>
	<OMHPolyline
	coordinates={[
	{ latitude: 37.78825, longitude: -122.4324 },
	{ latitude: 37.78925, longitude: -122.4314 },
	]}
	strokeColor="#000"
	strokeWidth={3}
	/>
	</OMHMapView>

	const customMapStyle = [
	{
	elementType: 'geometry',
	stylers: [{ color: '#242f3e' }],
	},
	// Add more styles as needed
	];

	<OMHMapView
	style={styles.map}
	customMapStyle={customMapStyle}
	initialRegion={{
	latitude: 37.78825,
	longitude: -122.4324,
	latitudeDelta: 0.0922,
	longitudeDelta: 0.0421,
	}}
	/>