react-naver-maps-kit

NAVER Maps JavaScript API v3를 React에 맞게 포팅한 라이브러리입니다.

공식 문서 | Playground

설치

# npm
npm install react-naver-maps-kit

# yarn
yarn add react-naver-maps-kit

# pnpm
pnpm add react-naver-maps-kit

# bun
bun add react-naver-maps-kit

사용법

이 라이브러리를 사용하기 위해서는 네이버 클라우드 플랫폼에서 Maps API 키를 발급받아야 합니다.

기본 사용법

import { NaverMapProvider, NaverMap, Marker } from 'react-naver-maps-kit';

function App() {
  return (
    <NaverMapProvider ncpKeyId="YOUR_NCP_KEY_ID">
      <NaverMap
        defaultCenter={{ lat: 37.3595704, lng: 127.105399 }}
        defaultZoom={15}
        style={{ width: '100%', height: '400px' }}
      >
        <Marker position={{ lat: 37.3595704, lng: 127.105399 }} />
      </NaverMap>
    </NaverMapProvider>
  );
}

커스텀 마커

React 컴포넌트를 마커로 사용할 수 있습니다.

<Marker position={{ lat: 37.3595704, lng: 127.105399 }}>
  <div style={{ padding: '8px 16px', background: '#03C75A', color: 'white', borderRadius: '20px' }}>
    네이버 그린팩토리
  </div>
</Marker>

컴포넌트

지도

컴포넌트	설명
NaverMapProvider	SDK 로딩 및 인증 관리
NaverMap	지도 컨테이너
Panorama	거리뷰 (panorama 서브모듈 필요)

오버레이

컴포넌트	설명
Marker	마커 (커스텀 콘텐츠 지원)
InfoWindow	정보창
Polyline	선
Polygon	다각형
Circle	원
Ellipse	타원
Rectangle	사각형
GroundOverlay	이미지 오버레이

서브모듈

필요한 서브모듈만 선택적으로 로드할 수 있습니다.

<NaverMapProvider ncpKeyId="YOUR_KEY" submodules={['panorama', 'visualization']}>
  {/* ... */}
</NaverMapProvider>

서브모듈	컴포넌트
panorama	Panorama, FlightSpot
visualization	HeatMap, DotMap
drawing	DrawingManager
geocoder	Geocoding 유틸리티

Hooks

import { useNaverMap, useMap } from 'react-naver-maps-kit';

// SDK 상태 접근
const { sdkStatus, sdkError } = useNaverMap();

// 지도 인스턴스 접근 (NaverMap 내부에서)
const map = useMap();

TypeScript

naver 전역 타입을 사용하려면 @types/navermaps를 설치하고 tsconfig.json을 설정하세요.

npm install -D @types/navermaps

{
  "compilerOptions": {
    "types": ["navermaps"]
  }
}

문서

자세한 사용법은 공식 문서를 참고하세요.

• 시작하기
• 지도 통합
• 오버레이 가이드
• API Reference

라이선스

MIT © 2026 cobocho

---

Disclaimer: 이 라이브러리는 NAVER의 공식 라이브러리가 아닙니다. NAVER Maps API의 서드파티 React 바인딩입니다.