NaverMapView

네이버 지도를 화면에 렌더링하는 핵심 컴포넌트입니다. 카메라, 지도 유형, 레이어 그룹, 제스처, 클러스터링, 위치 오버레이 등 지도의 모든 동작을 제어합니다.

임포트

import { NaverMapView } from '@boostbrothers/react-native-naver-map';

기본 사용법

import React, { useRef } from 'react';
import { NaverMapView, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

export default function MapScreen() {
  const mapRef = useRef<NaverMapViewRef>(null);

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{
        latitude: 37.5666102,
        longitude: 126.9783881,
        zoom: 14,
        tilt: 0,
        bearing: 0,
      }}
      onInitialized={() => {
        console.log('지도 초기화 완료');
      }}
      onCameraChanged={(params) => {
        console.log('카메라 변경:', params);
      }}
    />
  );
}

Props

지도 외관

Prop	타입	기본값	설명
`mapType`	`MapType`	`'Basic'`	지도 유형. Basic, Navi, Satellite, Hybrid, Terrain, NaviHybrid, None
`layerGroups`	`object`	`{ BUILDING: true, 나머지: false }`	레이어 그룹 활성화 여부
`isIndoorEnabled`	`boolean`	`false`	실내지도 활성화 (Basic, Terrain만 지원)
`isNightModeEnabled`	`boolean`	`false`	야간 모드 활성화 (Navi만 지원)
`isLiteModeEnabled`	`boolean`	`false`	라이트 모드 활성화. 로딩 속도 향상, 일부 기능 제한
`lightness`	`number`	`0`	지도 밝기 (-1 ~ 1)
`buildingHeight`	`number`	`1`	건물 입체 높이 비율 (0 ~ 1)
`symbolScale`	`number`	`1`	심벌 크기 비율 (0 ~ 2)
`symbolPerspectiveRatio`	`number`	`1`	심벌 원근 효과 비율 (0 ~ 1)
`locale`	`string`	시스템 로케일	지도 언어 (예: `'ko'`, `'en'`, `'ja'`)
`customStyleId`	`string`	-	네이버 스타일 에디터 커스텀 스타일 ID

layerGroups 상세

layerGroups={{
  BUILDING: true,   // 건물 형상, 주소 심벌 (기본 활성화)
  TRAFFIC: false,   // 실시간 교통정보
  TRANSIT: false,   // 철도, 지하철, 버스정류장
  BICYCLE: false,   // 자전거 도로, 주차대
  MOUNTAIN: false,  // 등산로, 등고선
  CADASTRAL: false, // 지적편집도
}}

카메라

Prop	타입	기본값	설명
`camera`	`Camera`	-	카메라 위치 (변경 시 지도가 이동)
`initialCamera`	`Camera`	-	초기 카메라 위치 (마운트 후 변경 불가)
`region`	`Region`	-	보여줄 영역 (`camera`가 있으면 무시)
`initialRegion`	`Region`	-	초기 영역 (마운트 후 변경 불가)
`animationDuration`	`number`	`0`	카메라 이동 애니메이션 지속시간 (ms)
`animationEasing`	`CameraAnimationEasing`	`'EaseOut'`	카메라 이동 애니메이션 이징
`minZoom`	`number`	-	최소 줌 레벨
`maxZoom`	`number`	-	최대 줌 레벨
`extent`	`Region`	-	카메라 이동 가능 영역 제한
`isExtentBoundedInKorea`	`boolean`	-	한반도로 카메라 영역 제한 (`extent`가 있으면 무시)

camera와 region을 동시에 사용하면 camera가 우선합니다. 초기 설정에는 initialCamera 또는 initialRegion을 사용하고, 이후 동적 변경에는 camera 또는 region을 사용하세요.

UI 컨트롤

Prop	타입	기본값	설명
`isShowCompass`	`boolean`	-	나침반 표시 여부 (회전/틸트 시 표시)
`isShowScaleBar`	`boolean`	-	축척 바 표시 여부
`isShowZoomControls`	`boolean`	-	줌 버튼 표시 여부
`isShowIndoorLevelPicker`	`boolean`	-	실내지도 층 피커 표시 여부
`isShowLocationButton`	`boolean`	-	현위치 버튼 표시 여부
`mapPadding`	`Partial<Rect>`	-	지도 콘텐츠 패딩
`logoAlign`	`LogoAlign`	-	네이버 로고 위치 (TopLeft, TopRight, BottomLeft, BottomRight)
`logoMargin`	`Partial<Rect>`	-	네이버 로고 마진

제스처

Prop	타입	기본값	설명
`isScrollGesturesEnabled`	`boolean`	-	스크롤 제스처 활성화
`isZoomGesturesEnabled`	`boolean`	-	줌 제스처 활성화
`isTiltGesturesEnabled`	`boolean`	-	틸트 제스처 활성화
`isRotateGesturesEnabled`	`boolean`	-	회전 제스처 활성화
`isStopGesturesEnabled`	`boolean`	-	스톱 제스처 활성화 (애니메이션 탭으로 중단)

성능

Prop	타입	기본값	설명
`fpsLimit`	`number`	`0`	최대 FPS 제한 (0 = 무제한, Android 전용, 초기화 시에만 적용)
`isUseTextureViewAndroid`	`boolean`	-	Android에서 TextureView 사용 (초기화 시에만 적용)

클러스터링

마커 클러스터링은 clusters prop으로 설정합니다. 자세한 내용은 클러스터링 기능을 참고하세요.

clusters={[
  {
    markers: [
      { identifier: 'marker1', latitude: 37.5, longitude: 126.9 },
      { identifier: 'marker2', latitude: 37.51, longitude: 126.91 },
    ],
    screenDistance: 200,
    minZoom: 0,
    maxZoom: 21,
    animate: true,
    width: 40,
    height: 40,
  }
]}

위치 오버레이

현재 사용자 위치를 나타내는 특수 오버레이를 설정합니다.

locationOverlay={{
  isVisible: true,
  position: { latitude: 37.5666102, longitude: 126.9783881 },
  bearing: 90,
  image: { symbol: 'green' },
  imageWidth: 40,
  imageHeight: 40,
  anchor: { x: 0.5, y: 0.5 },
  circleRadius: 50,
  circleColor: 'rgba(0, 128, 255, 0.2)',
  circleOutlineWidth: 1,
  circleOutlineColor: 'rgba(0, 128, 255, 0.5)',
}}

속성	타입	기본값	설명
`isVisible`	`boolean`	`false`	표시 여부
`position`	`Coord`	-	오버레이 좌표
`bearing`	`number`	`0`	방향 각도
`image`	`MapImageProp`	-	메인 아이콘 이미지
`imageWidth`	`number`	`SIZE_AUTO`	메인 아이콘 너비
`imageHeight`	`number`	`SIZE_AUTO`	메인 아이콘 높이
`anchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	메인 아이콘 앵커
`subImage`	`MapImageProp`	-	서브 아이콘 이미지
`subImageWidth`	`number`	`SIZE_AUTO`	서브 아이콘 너비
`subImageHeight`	`number`	`SIZE_AUTO`	서브 아이콘 높이
`subAnchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	서브 아이콘 앵커
`circleRadius`	`number`	`0`	강조 원 반경 (픽셀)
`circleColor`	`ColorValue`	-	강조 원 색상
`circleOutlineWidth`	`number`	`0`	강조 원 테두리 두께
`circleOutlineColor`	`ColorValue`	-	강조 원 테두리 색상

이벤트

Prop	타입	설명
`onInitialized`	`() => void`	지도 초기화 완료
`onCameraChanged`	`(params: Camera & { reason: CameraChangeReason; region: Region }) => void`	카메라 변경 시
`onCameraIdle`	`(params: Camera & { region: Region }) => void`	카메라 이동 종료 시
`onTapMap`	`(params: Coord & { x: number; y: number }) => void`	지도 탭 시
`onOptionChanged`	`(params: { locationTrackingMode: LocationTrackingMode }) => void`	지도 옵션 변경 시
`onTapClusterLeaf`	`(params: { markerIdentifier: string }) => void`	클러스터 리프 마커 탭 시
`onCustomStyleLoaded`	`() => void`	커스텀 스타일 로드 완료
`onCustomStyleLoadFailed`	`(params: { message: string }) => void`	커스텀 스타일 로드 실패

Ref 메서드 (NaverMapViewRef)

ref를 통해 명령형으로 카메라를 제어하고 좌표를 변환할 수 있습니다.

const mapRef = useRef<NaverMapViewRef>(null);

// 카메라 이동
mapRef.current?.animateCameraTo({
  latitude: 37.5666102,
  longitude: 126.9783881,
  zoom: 14,
  duration: 700,
  easing: 'EaseOut',
});

메서드	설명
`animateCameraTo(params)`	특정 좌표로 카메라 이동
`animateCameraBy(params)`	현재 위치에서 델타값만큼 카메라 이동
`animateRegionTo(params)`	특정 Region으로 카메라 이동
`animateCameraWithTwoCoords(params)`	두 좌표가 모두 보이는 줌 레벨로 이동
`cancelAnimation()`	진행 중인 카메라 애니메이션 취소
`setLocationTrackingMode(mode)`	위치 추적 모드 변경
`screenToCoordinate(params)`	화면 좌표 → 위경도 변환 (Promise)
`coordinateToScreen(params)`	위경도 → 화면 좌표 변환 (Promise)

자세한 내용은 카메라 제어 문서를 참고하세요.

전체 예제

import React, { useRef, useState } from 'react';
import { Button, StyleSheet, View } from 'react-native';
import {
  NaverMapView,
  NaverMapMarkerOverlay,
  type NaverMapViewRef,
} from '@boostbrothers/react-native-naver-map';

export default function FullMapExample() {
  const mapRef = useRef<NaverMapViewRef>(null);
  const [cameraInfo, setCameraInfo] = useState('');

  return (
    <View style={styles.container}>
      <NaverMapView
        ref={mapRef}
        style={styles.map}
        mapType="Basic"
        layerGroups={{ BUILDING: true, TRAFFIC: true, TRANSIT: false, BICYCLE: false, MOUNTAIN: false, CADASTRAL: false }}
        initialCamera={{
          latitude: 37.5666102,
          longitude: 126.9783881,
          zoom: 14,
          tilt: 0,
          bearing: 0,
        }}
        isShowCompass
        isShowScaleBar
        isShowZoomControls
        onInitialized={() => console.log('초기화 완료')}
        onCameraChanged={({ latitude, longitude, zoom, reason }) => {
          setCameraInfo(`위도: ${latitude.toFixed(4)}, 경도: ${longitude.toFixed(4)}, 줌: ${zoom?.toFixed(1)}`);
        }}
        onTapMap={({ latitude, longitude }) => {
          console.log(`탭: ${latitude}, ${longitude}`);
        }}
      >
        <NaverMapMarkerOverlay
          latitude={37.5666102}
          longitude={126.9783881}
          caption={{ text: '서울 시청' }}
        />
      </NaverMapView>
      <Button
        title="서울로 이동"
        onPress={() => {
          mapRef.current?.animateCameraTo({
            latitude: 37.5666102,
            longitude: 126.9783881,
            zoom: 14,
            duration: 700,
            easing: 'EaseOut',
          });
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  map: { flex: 1 },
});

NaverMapView

임포트

import { NaverMapView } from '@boostbrothers/react-native-naver-map';

기본 사용법

import React, { useRef } from 'react';
import { NaverMapView, type NaverMapViewRef } from '@boostbrothers/react-native-naver-map';

export default function MapScreen() {
  const mapRef = useRef<NaverMapViewRef>(null);

  return (
    <NaverMapView
      ref={mapRef}
      style={{ flex: 1 }}
      initialCamera={{
        latitude: 37.5666102,
        longitude: 126.9783881,
        zoom: 14,
        tilt: 0,
        bearing: 0,
      }}
      onInitialized={() => {
        console.log('지도 초기화 완료');
      }}
      onCameraChanged={(params) => {
        console.log('카메라 변경:', params);
      }}
    />
  );
}

Props

지도 외관

Prop	타입	기본값	설명
`mapType`	`MapType`	`'Basic'`	지도 유형. Basic, Navi, Satellite, Hybrid, Terrain, NaviHybrid, None
`layerGroups`	`object`	`{ BUILDING: true, 나머지: false }`	레이어 그룹 활성화 여부
`isIndoorEnabled`	`boolean`	`false`	실내지도 활성화 (Basic, Terrain만 지원)
`isNightModeEnabled`	`boolean`	`false`	야간 모드 활성화 (Navi만 지원)
`isLiteModeEnabled`	`boolean`	`false`	라이트 모드 활성화. 로딩 속도 향상, 일부 기능 제한
`lightness`	`number`	`0`	지도 밝기 (-1 ~ 1)
`buildingHeight`	`number`	`1`	건물 입체 높이 비율 (0 ~ 1)
`symbolScale`	`number`	`1`	심벌 크기 비율 (0 ~ 2)
`symbolPerspectiveRatio`	`number`	`1`	심벌 원근 효과 비율 (0 ~ 1)
`locale`	`string`	시스템 로케일	지도 언어 (예: `'ko'`, `'en'`, `'ja'`)
`customStyleId`	`string`	-	네이버 스타일 에디터 커스텀 스타일 ID

layerGroups 상세

layerGroups={{
  BUILDING: true,   // 건물 형상, 주소 심벌 (기본 활성화)
  TRAFFIC: false,   // 실시간 교통정보
  TRANSIT: false,   // 철도, 지하철, 버스정류장
  BICYCLE: false,   // 자전거 도로, 주차대
  MOUNTAIN: false,  // 등산로, 등고선
  CADASTRAL: false, // 지적편집도
}}

카메라

Prop	타입	기본값	설명
`camera`	`Camera`	-	카메라 위치 (변경 시 지도가 이동)
`initialCamera`	`Camera`	-	초기 카메라 위치 (마운트 후 변경 불가)
`region`	`Region`	-	보여줄 영역 (`camera`가 있으면 무시)
`initialRegion`	`Region`	-	초기 영역 (마운트 후 변경 불가)
`animationDuration`	`number`	`0`	카메라 이동 애니메이션 지속시간 (ms)
`animationEasing`	`CameraAnimationEasing`	`'EaseOut'`	카메라 이동 애니메이션 이징
`minZoom`	`number`	-	최소 줌 레벨
`maxZoom`	`number`	-	최대 줌 레벨
`extent`	`Region`	-	카메라 이동 가능 영역 제한
`isExtentBoundedInKorea`	`boolean`	-	한반도로 카메라 영역 제한 (`extent`가 있으면 무시)

UI 컨트롤

Prop	타입	기본값	설명
`isShowCompass`	`boolean`	-	나침반 표시 여부 (회전/틸트 시 표시)
`isShowScaleBar`	`boolean`	-	축척 바 표시 여부
`isShowZoomControls`	`boolean`	-	줌 버튼 표시 여부
`isShowIndoorLevelPicker`	`boolean`	-	실내지도 층 피커 표시 여부
`isShowLocationButton`	`boolean`	-	현위치 버튼 표시 여부
`mapPadding`	`Partial<Rect>`	-	지도 콘텐츠 패딩
`logoAlign`	`LogoAlign`	-	네이버 로고 위치 (TopLeft, TopRight, BottomLeft, BottomRight)
`logoMargin`	`Partial<Rect>`	-	네이버 로고 마진

제스처

Prop	타입	기본값	설명
`isScrollGesturesEnabled`	`boolean`	-	스크롤 제스처 활성화
`isZoomGesturesEnabled`	`boolean`	-	줌 제스처 활성화
`isTiltGesturesEnabled`	`boolean`	-	틸트 제스처 활성화
`isRotateGesturesEnabled`	`boolean`	-	회전 제스처 활성화
`isStopGesturesEnabled`	`boolean`	-	스톱 제스처 활성화 (애니메이션 탭으로 중단)

성능

Prop	타입	기본값	설명
`fpsLimit`	`number`	`0`	최대 FPS 제한 (0 = 무제한, Android 전용, 초기화 시에만 적용)
`isUseTextureViewAndroid`	`boolean`	-	Android에서 TextureView 사용 (초기화 시에만 적용)

클러스터링

마커 클러스터링은 clusters prop으로 설정합니다. 자세한 내용은 클러스터링 기능을 참고하세요.

clusters={[
  {
    markers: [
      { identifier: 'marker1', latitude: 37.5, longitude: 126.9 },
      { identifier: 'marker2', latitude: 37.51, longitude: 126.91 },
    ],
    screenDistance: 200,
    minZoom: 0,
    maxZoom: 21,
    animate: true,
    width: 40,
    height: 40,
  }
]}

위치 오버레이

현재 사용자 위치를 나타내는 특수 오버레이를 설정합니다.

locationOverlay={{
  isVisible: true,
  position: { latitude: 37.5666102, longitude: 126.9783881 },
  bearing: 90,
  image: { symbol: 'green' },
  imageWidth: 40,
  imageHeight: 40,
  anchor: { x: 0.5, y: 0.5 },
  circleRadius: 50,
  circleColor: 'rgba(0, 128, 255, 0.2)',
  circleOutlineWidth: 1,
  circleOutlineColor: 'rgba(0, 128, 255, 0.5)',
}}

속성	타입	기본값	설명
`isVisible`	`boolean`	`false`	표시 여부
`position`	`Coord`	-	오버레이 좌표
`bearing`	`number`	`0`	방향 각도
`image`	`MapImageProp`	-	메인 아이콘 이미지
`imageWidth`	`number`	`SIZE_AUTO`	메인 아이콘 너비
`imageHeight`	`number`	`SIZE_AUTO`	메인 아이콘 높이
`anchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	메인 아이콘 앵커
`subImage`	`MapImageProp`	-	서브 아이콘 이미지
`subImageWidth`	`number`	`SIZE_AUTO`	서브 아이콘 너비
`subImageHeight`	`number`	`SIZE_AUTO`	서브 아이콘 높이
`subAnchor`	`{ x: number; y: number }`	`{ x: 0.5, y: 0.5 }`	서브 아이콘 앵커
`circleRadius`	`number`	`0`	강조 원 반경 (픽셀)
`circleColor`	`ColorValue`	-	강조 원 색상
`circleOutlineWidth`	`number`	`0`	강조 원 테두리 두께
`circleOutlineColor`	`ColorValue`	-	강조 원 테두리 색상

이벤트

Prop	타입	설명
`onInitialized`	`() => void`	지도 초기화 완료
`onCameraChanged`	`(params: Camera & { reason: CameraChangeReason; region: Region }) => void`	카메라 변경 시
`onCameraIdle`	`(params: Camera & { region: Region }) => void`	카메라 이동 종료 시
`onTapMap`	`(params: Coord & { x: number; y: number }) => void`	지도 탭 시
`onOptionChanged`	`(params: { locationTrackingMode: LocationTrackingMode }) => void`	지도 옵션 변경 시
`onTapClusterLeaf`	`(params: { markerIdentifier: string }) => void`	클러스터 리프 마커 탭 시
`onCustomStyleLoaded`	`() => void`	커스텀 스타일 로드 완료
`onCustomStyleLoadFailed`	`(params: { message: string }) => void`	커스텀 스타일 로드 실패

Ref 메서드 (NaverMapViewRef)

ref를 통해 명령형으로 카메라를 제어하고 좌표를 변환할 수 있습니다.

const mapRef = useRef<NaverMapViewRef>(null);

// 카메라 이동
mapRef.current?.animateCameraTo({
  latitude: 37.5666102,
  longitude: 126.9783881,
  zoom: 14,
  duration: 700,
  easing: 'EaseOut',
});

메서드	설명
`animateCameraTo(params)`	특정 좌표로 카메라 이동
`animateCameraBy(params)`	현재 위치에서 델타값만큼 카메라 이동
`animateRegionTo(params)`	특정 Region으로 카메라 이동
`animateCameraWithTwoCoords(params)`	두 좌표가 모두 보이는 줌 레벨로 이동
`cancelAnimation()`	진행 중인 카메라 애니메이션 취소
`setLocationTrackingMode(mode)`	위치 추적 모드 변경
`screenToCoordinate(params)`	화면 좌표 → 위경도 변환 (Promise)
`coordinateToScreen(params)`	위경도 → 화면 좌표 변환 (Promise)

자세한 내용은 카메라 제어 문서를 참고하세요.

전체 예제

import React, { useRef, useState } from 'react';
import { Button, StyleSheet, View } from 'react-native';
import {
  NaverMapView,
  NaverMapMarkerOverlay,
  type NaverMapViewRef,
} from '@boostbrothers/react-native-naver-map';

export default function FullMapExample() {
  const mapRef = useRef<NaverMapViewRef>(null);
  const [cameraInfo, setCameraInfo] = useState('');

  return (
    <View style={styles.container}>
      <NaverMapView
        ref={mapRef}
        style={styles.map}
        mapType="Basic"
        layerGroups={{ BUILDING: true, TRAFFIC: true, TRANSIT: false, BICYCLE: false, MOUNTAIN: false, CADASTRAL: false }}
        initialCamera={{
          latitude: 37.5666102,
          longitude: 126.9783881,
          zoom: 14,
          tilt: 0,
          bearing: 0,
        }}
        isShowCompass
        isShowScaleBar
        isShowZoomControls
        onInitialized={() => console.log('초기화 완료')}
        onCameraChanged={({ latitude, longitude, zoom, reason }) => {
          setCameraInfo(`위도: ${latitude.toFixed(4)}, 경도: ${longitude.toFixed(4)}, 줌: ${zoom?.toFixed(1)}`);
        }}
        onTapMap={({ latitude, longitude }) => {
          console.log(`탭: ${latitude}, ${longitude}`);
        }}
      >
        <NaverMapMarkerOverlay
          latitude={37.5666102}
          longitude={126.9783881}
          caption={{ text: '서울 시청' }}
        />
      </NaverMapView>
      <Button
        title="서울로 이동"
        onPress={() => {
          mapRef.current?.animateCameraTo({
            latitude: 37.5666102,
            longitude: 126.9783881,
            zoom: 14,
            duration: 700,
            easing: 'EaseOut',
          });
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  map: { flex: 1 },
});

NaverMapView

NaverMapView

임포트

기본 사용법

Props

지도 외관

layerGroups 상세

카메라

UI 컨트롤

제스처

성능

클러스터링

위치 오버레이

이벤트

Ref 메서드 (NaverMapViewRef)

전체 예제

목차

NaverMapView

NaverMapView

임포트

기본 사용법

Props

지도 외관

layerGroups 상세

카메라

UI 컨트롤

제스처

성능

클러스터링

위치 오버레이

이벤트

Ref 메서드 (NaverMapViewRef)

전체 예제

목차