repository·main·Indexed 41 days ago
https://github.com/mym0404/react-native-naver-mapA React Native wrapper for Naver Maps (version 2.9.0) that enables high-performance map integration for Android and iOS. It provides the NaverMapView component, shape overlays (circles, polygons, paths), and various marker types including custom views and HTTP images. Features include programmatic camera control via NaverMapViewRef, support for both initial and controlled camera props, and an Expo Config Plugin for automated native configuration.
React Native Naver Map is a library that allows developers to integrate Naver Maps into React Native applications. It provides a bridge to use Naver Map capabilities within the React Native ecosystem.
Important Note on API Versions:
Starting from version 2.4.x, the library supports the newly released standalone Maps product, which is distinct from the Map API previously provided by the AI NAVER API.
React Native Naver Map provides several core components for map integration. The primary components are:
A locationOverlay is a specialized overlay used to represent the user's current location on the map. Unlike other overlays, there can only be one location overlay per map instance, and it cannot be manually instantiated as a separate component; instead, it is managed via the locationOverlay prop on the NaverMapView component.
If location permissions are correctly configured and location tracking is enabled, the overlay will automatically appear and track the user's position. You can use the locationOverlay prop to customize its appearance and behavior without needing to manually manage position updates.
Overlays are rendered in a hierarchical structure controlled by two types of Z-Index values:
globalZIndex: Determines the rendering order between different overlay types (e.g., Markers vs. Polygons).
zIndex: Determines the order between overlays of the same type (those sharing the same globalZIndex).
0.Note: zIndex cannot override the hierarchy established by globalZIndex. For example, a Marker (globalZIndex: 200,000) will always appear above a Ground Overlay (globalZIndex: -300,000), even if the Ground Overlay has a higher zIndex.
You can position the map using two different data structures:
Use Camera when you need specific angles and tilt, and Region when you want to ensure a specific geographic area is visible.
// Camera configuration
const camera: Camera = {
latitude: 37.5665,
longitude: 126.9780,
zoom: 14,
tilt: 30,
bearing: 45,
};
// Region configuration
const region: Region = {
latitude: 37.5665,
longitude: 126.9780,
latitudeDelta: 0.05,
longitudeDelta: 0.05,
};The project is moving towards a modular architecture where different functionalities are separated into independent packages. This allows for modular installation and reduced bundle sizes.
@react-native-naver-map/core: Contains the basic map components (the current primary package).@react-native-naver-map/cloud-services: Dedicated package for Naver Cloud API integrations (Directions, Geocoding, etc.).@react-native-naver-map/utils: Common utilities used across the ecosystem.NaverMapView distinguishes between props used for initial setup and those used for active control:
initialCamera, initialRegion): Applied only when the map is first loaded. Use these if you want to set a starting position but allow the user to move the map freely without your app forcing it back.camera, region): The map will move to these values whenever the props change. Use these for full programmatic control or when syncing map state with React state.Performance Tip: onCameraChanged is called frequently during user interaction. It is highly recommended to use a debounce function to prevent excessive state updates or API calls.
// Controlled pattern: Syncing state with map movement
const [camera, setCamera] = useState<Camera>({
latitude: 37.5665,
longitude: 126.9780,
zoom: 14,
});
<NaverMapView
camera={camera}
onCameraChanged={({ latitude, longitude, zoom, bearing, tilt }) => {
setCamera({ latitude, longitude, zoom, bearing, tilt });
}}
/>The useInfoWindow hook creates and manages a native text InfoWindow instance. It allows you to display text information on the map, either anchored to a specific NaverMapMarkerOverlay or at a specific map coordinate.
Key behaviors:
anchor, offset, and alpha) whenever the configuration object passed to the hook changes.showOnMarker and showOnMap return a boolean indicating if the command was successfully sent. If the target ref (map or marker) is not yet ready, these methods return false.const infoWindow = useInfoWindow({
text: 'Seoul Station',
anchor: { x: 0.5, y: 1 },
offset: { x: 0, y: -8 },
alpha: 0.9,
});The NaverMapView component distinguishes between initial setup and active control of the map position:
initialCamera, initialRegion): These values are applied only when the map first loads. After loading, the user can freely manipulate the map without the props forcing it back to these values.camera, region): These properties actively control the map. Whenever the value of these props changes, the map will move to the specified location. To use these correctly, you must implement two-way data binding using React state and the onCameraChanged callback.import React, { useState } from 'react';
import { NaverMapView, Camera } from '@mj-studio/react-native-naver-map';
const ControlledCameraExample = () => {
const [camera, setCamera] = useState<Camera>({
latitude: 37.5665,
longitude: 126.9780,
zoom: 14,
});
return (
<NaverMapView
style={{ flex: 1 }}
camera={camera} // Controlled property
onCameraChanged={({ latitude, longitude, zoom, bearing, tilt }) => {
// Update state when user manipulates the map to maintain sync
setCamera({ latitude, longitude, zoom, bearing, tilt });
}}
/>
);
};You can position the map using two different data structures:
latitudeDelta and longitudeDelta.// Camera approach
const camera: Camera = {
latitude: 37.5665,
longitude: 126.9780,
zoom: 14,
tilt: 30,
bearing: 45,
};
// Region approach
const region: Region = {
latitude: 37.5665,
longitude: 126.9780,
latitudeDelta: 0.05,
longitudeDelta: 0.05,
};Overlays are rendered in a hierarchical structure controlled by two types of Z-Index:
globalZIndex: Determines the hierarchy between different types of overlays (e.g., Markers vs. Polygons).
zIndex: Controls the rendering order among overlays of the same globalZIndex (i.e., the same type).
Note: zIndex is more intuitive for managing priority within a specific group of overlays. Changing a marker's zIndex will not make it appear below a polygon if the polygon's globalZIndex is lower.
// Default globalZIndex hierarchy reference:
// Info Windows: 400000
// Location Overlay: 300000
// Markers: 200000
// Arrow Overlays: 100000
// (Map Symbols = 0)
// Path Overlays: -100000
// Shapes (Polygon, Polyline, Circle): -200000
// Ground Overlays: -300000The useInfoWindow hook creates and controls a native text-based InfoWindow instance. You can display the same InfoWindow either on top of a NaverMapMarkerOverlay or at specific map coordinates.
Key behaviors:
const infoWindow = useInfoWindow({
text: 'Content',
anchor: { x: 0.5, y: 1 },
offset: { x: 0, y: -8 },
alpha: 0.9,
});