React Native Naver Map

@boostbrothers/react-native-naver-map — 네이버 지도 SDK(NMapsMap)를 React Native에서 사용할 수 있도록 래핑한 라이브러리. 선언적 React 컴포넌트 방식으로 지도를 렌더링합니다.

When to Apply

Reference this skill when:

• 네이버 지도 컴포넌트를 구현할 때
• 마커, 경로선, 폴리곤 등 오버레이를 추가할 때
• 카메라 애니메이션, 좌표 변환 작업 시
• 마커 클러스터링을 구현할 때
• 위치 추적 모드를 설정할 때

Component Quick Reference

Component	Description
NaverMapView	지도를 렌더링하는 메인 컴포넌트
NaverMapMarkerOverlay	지도 위에 마커를 표시
NaverMapInfoWindow	마커 또는 좌표 위에 정보창 표시
NaverMapPathOverlay	경로선 표시 (진척률 지원)
NaverMapPolylineOverlay	폴리라인 표시
NaverMapPolygonOverlay	다각형 영역 표시
NaverMapCircleOverlay	원형 영역 표시
NaverMapArrowheadPathOverlay	화살표 머리가 있는 경로선
NaverMapMultiPathOverlay	구간별 색상이 다른 다중 경로선
NaverMapGroundOverlay	특정 지도 영역에 이미지 표시

NaverMapViewRef Methods

Method	Description
animateCameraTo(params)	특정 좌표로 카메라 이동 (애니메이션)
animateCameraBy(params)	현재 위치에서 상대적으로 카메라 이동
animateRegionTo(params)	특정 영역으로 카메라 이동
animateCameraWithTwoCoords(params)	두 좌표를 기준으로 자동 줌
cancelAnimation()	진행 중인 카메라 애니메이션 취소
setLocationTrackingMode(mode)	위치 추적 모드 설정
screenToCoordinate(point)	화면 좌표 → 위경도 좌표 변환
coordinateToScreen(coord)	위경도 좌표 → 화면 좌표 변환

Key Types Summary

MapType: Basic | Navi | Satellite | Hybrid | Terrain | NaviHybrid

LocationTrackingMode: None | NoFollow | Follow | Face

CameraAnimationEasing: None | Fly | Linear | EaseIn | EaseOut

CameraMoveBaseParams: duration?, easing?, pivot?

MapImageProp: 마커 및 오버레이에서 사용하는 이미지 타입

BaseOverlayProps: zIndex?, globalZIndex?, isHidden?, minZoom?, maxZoom?, isMinZoomInclusive?, isMaxZoomInclusive?, onTap?

Main Features

지도 유형

NaverMapView의 mapType prop으로 설정:

<NaverMapView mapType="Navi" style={{ flex: 1 }} />

레이어 그룹

건물, 교통, 대중교통, 자전거, 등산로, 지적편집도 레이어를 on/off.

마커 클러스터링

줌 레벨에 따라 근접 마커들을 자동 클러스터링. onTapClusterLeaf 콜백으로 클러스터 내 마커 탭 처리.

카메라 제어

ref를 통한 명령형 제어:

const mapRef = useRef<NaverMapViewRef>(null);
mapRef.current?.animateCameraTo({
  latitude: 37.5665,
  longitude: 126.9780,
  duration: 1000,
  easing: 'EaseOut',
});

위치 추적

4가지 모드: None(끔), NoFollow(위치만 표시), Follow(위치+카메라 추적), Face(방향+카메라 추적).

좌표 변환

화면 좌표 ↔ 위경도 좌표 변환:

const coord = await mapRef.current?.screenToCoordinate({ x: 100, y: 200 });
const point = await mapRef.current?.coordinateToScreen({ latitude: 37.5, longitude: 127.0 });

Architecture

React Native JS/TS Layer
  ↓ (JSX Props)
NaverMapView Component
  ↓ (React Native Bridge)
Native Module
  ├── iOS: NMapsMap.framework
  └── Android: naver-map-sdk

네이버 지도 API 클라이언트 ID가 반드시 등록되어야 합니다 (iOS Info.plist, Android AndroidManifest.xml).

How to Use

Read individual reference files for detailed API and troubleshooting:

rules/api-components.md   — 10개 컴포넌트 상세 Props
rules/api-types.md        — 모든 타입, 인터페이스, Enum
rules/troubleshooting.md  — iOS/Android 빌드 오류, Expo 이슈

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md