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 바인딩입니다.