This is the full developer documentation for react-naver-maps-kit.
# Start of react-naver-maps-kit documentation
# React Naver Maps KIT
react-naver-maps-kit is a React binding for NAVER Maps JavaScript API v3.
It provides declarative map/overlay components, lifecycle-safe instance management, and TypeScript-first APIs.
This full document aggregates the official project docs for LLM consumption.
Main docs site: https://react-naver-maps-kit.pages.dev/
## Primary Links
- Home: https://react-naver-maps-kit.pages.dev/
- Getting Started: https://react-naver-maps-kit.pages.dev/guide/getting-started
- Core Concepts: https://react-naver-maps-kit.pages.dev/guide/core-concepts
- API Index (entry): https://react-naver-maps-kit.pages.dev/api/provider
- Examples Index (entry): https://react-naver-maps-kit.pages.dev/examples/markers
- Troubleshooting: https://react-naver-maps-kit.pages.dev/troubleshooting/common-issues
- Playground: https://react-naver-maps-kit-playground.pages.dev
---
# Full Documentation Sources
---
## Source File: index.md
- URL: https://react-naver-maps-kit.pages.dev/
- Local Path: packages/docs/index.md
## Quick start
### installation
::: code-group
```bash [pnpm]
pnpm add react-naver-maps-kit
```
```bash [npm]
npm install react-naver-maps-kit
```
```bash [yarn]
yarn add react-naver-maps-kit
```
:::
### The first map
```tsx
import { NaverMapProvider, NaverMap, Marker } from "react-naver-maps-kit";
function App() {
return (
);
}
```
### Custom Markers
```tsx
Seoul City Hall
```
## Component
### map
| component | Description |
| ---------------------------------------- | --------------------- |
| [`NaverMapProvider`](/api/provider) | SDK loading and authentication management |
| [`NaverMap`](/api/map) | map container |
| [`Panorama`](/guide/submodules/panorama) | street view |
###Overlay
| component | Description |
| ------------------------------------------ | ------------------------- |
| [`Marker`](/api/marker) | Marker (custom content support) |
| [`MarkerClusterer`](/api/marker-clusterer) | marker clustering |
| [`InfoWindow`](/api/info-window) | Information Window |
| [`Polyline`](/api/polyline) | line |
| [`Polygon`](/api/polygon) | polygon |
| [`Circle`](/api/circle) | won |
| [`Rectangle`](/api/rectangle) | square |
### Submodule
| Submodule | component |
| -------------------------------------------------- | -------------------- |
| [`panorama`](/guide/submodules/panorama) | Panorama, FlightSpot |
| [`visualization`](/guide/submodules/visualization) | HeatMap, DotMap |
| [`drawing`](/guide/submodules/drawing) | DrawingManager |
| [`gl`](/guide/submodules/gl) | GL vector map |
---
> **Disclaimer**: This library is not NAVER's official library.
---
## Source File: guide/getting-started.md
- URL: https://react-naver-maps-kit.pages.dev/guide/getting-started
- Local Path: packages/docs/guide/getting-started.md
# Get started
This guide will guide you step by step through installing `react-naver-maps-kit` and creating your first map.
## Prerequisites
- React 18 or higher
- Node.js 18 or higher
- Naver Cloud Platform account (for API key issuance)
## Step 1: Installation
```bash
# pnpm (recommended)
pnpm add react-naver-maps-kit
# npm
npm install react-naver-maps-kit
# yarn
yarn add react-naver-maps-kit
```
### Peer Dependencies
This library requires the following packages as peer dependencies:
- `react >= 18`
- `react-dom >= 18`
### TypeScript support
This library is written in TypeScript and contains **complete type definitions**. To use the `naver.maps` global type, you must install `@types/navermaps` and set tsconfig.
#### 1. Install type package
```bash
# pnpm
pnpm add -D @types/navermaps
# npm
npm install -D @types/navermaps
# yarn
yarn add -D @types/navermaps
```
#### 2. tsconfig.json settings
Explicitly load the `navermaps` type by adding the `types` array to `compilerOptions`:
```json
{
"compilerOptions": {
"types": ["vite/client", "navermaps"]
// ... other settings
}
}
```
::: Why setting warning types is necessary
Newer module resolution methods, such as `moduleResolution: "bundler"`, may not automatically include `@types/*` packages. You must explicitly add `"navermaps"` to the `types` array for the `naver` global type to be recognized.
:::
#### 3. Example of type use
```tsx
import type { NaverMapRef, MarkerRef } from "react-naver-maps-kit";
// Use Naver Map SDK type
const handleMapReady = (map: naver.maps.Map) => {
const center = map.getCenter();
console.log(`Map center: ${center.lat()}, ${center.lng()}`);
};
```
::: Tip extension type automatically applied
`react-naver-maps-kit` extends some types missing in `@types/navermaps`. When you import the library, extension types such as `map.isReady` and `HeatMap.addData()` are automatically applied.
:::
## Step 2: Issue an API key
1. Log in to [Naver Cloud Platform](https://www.ncloud.com/)
2. Apply for **Maps** service in console
3. Issue API key after **Application registration**
### Select key type
| key type | Prop | Use |
| ----------------- | ------------- | -------------- |
| NCP Key ID (recommended) | `ncpKeyId` | General Web Services |
| NCP Client ID | `ncpClientId` | Legacy Compatible |
| Gov Client ID | `govClientId` | For public institutions |
| Fin Client ID | `finClientId` | For financial institutions |
### Domain registration
In your development environment, add the following domains to your whitelist:
```
http://localhost:5173
http://localhost:3000
http://127.0.0.1:5173
```
## Step 3: Setting environment variables
If you are using Vite, create a `.env.local` file:
```env
VITE_NCP_KEY_ID=your-ncp-key-id-here
```
::: warning
Do not commit your API key to a public repository. Add `.env.local` to `.gitignore`.
:::
## Step 4: Provider settings
Wrap it with `NaverMapProvider` at the top level of your app:
```tsx
// App.tsx
import { NaverMapProvider } from "react-naver-maps-kit";
function App() {
return (
console.log("Map SDK is ready!")}
onError={(error) => console.error("SDK loading failed:", error)}
>
{/* Map components go here */}
);
}
export default App;
```
### Provider Options
| Prop | default | Description |
| ------------ | ------- | ------------------------------------------------------------------------ |
| `ncpKeyId` | - | NCP API Key ID |
| `submodules` | `[]` | Additional submodules (`geocoder`, `panorama`, `drawing`, `visualization`, `gl`) |
| `timeoutMs` | `10000` | SDK loading timeout (ms) |
| `autoLoad` | `true` | Automatic loading when mounted |
| `onReady` | - | SDK loading completion callback |
| `onError` | - | Error Occurrence Callback |
::: tip submodule guide
For instructions on how to use submodules, please refer to each guide:
- [Geocoder](/guide/submodules/geocoder) - Address search, coordinate conversion
- [Panorama](/guide/submodules/panorama) - street view, aerial view
- [Drawing](/guide/submodules/drawing) - Drawing tools
- [Visualization](/guide/submodules/visualization) - heat map, point map
- [GL](/guide/submodules/gl) - WebGL vector maps
:::
## Step 5: Map Rendering
Display a map with the `NaverMap` component:
```tsx
// components/Map.tsx
import { NaverMap } from "react-naver-maps-kit";
function Map() {
return (
);
}
export default Map;
```
### Required Props
- `center`: Map center coordinates (`{ lat: number, lng: number }`)
- `zoom`: Zoom level (1~21)
- `style`: map container size (CSS style)
::: tip
Map height must be specified. `height: 100%` alone does not work.
:::
## Step 6: Add markers
Mark a location on a map with the `Marker` component:
```tsx
import { NaverMap, Marker } from "react-naver-maps-kit";
function MapWithMarker() {
return (
{
console.log("Marker clicked!", e.coord);
}}
/>
);
}
```
## Step 7: Handle loading status
Display SDK loading status and handle errors:
```tsx
import { NaverMap, NaverMapProvider, useNaverMap } from "react-naver-maps-kit";
function MapContainer() {
const { sdkStatus, sdkError, reloadSdk } = useNaverMap();
if (sdkStatus === "loading") {
return
Loading map...
;
}
if (sdkStatus === "error") {
return (
Map loading failed: {sdkError?.message}
);
}
return (
);
}
function App() {
return (
);
}
```
## Next steps
- [Core Concepts](/guide/core-concepts) - Understanding the operating principles of Provider, Map, and Hook
- [Submodule](/guide/submodules/geocoder) - How to use Geocoder, Panorama, Drawing, Visualization, GL modules
- [Marker examples](/examples/markers) - How to use various markers
- [API Reference](/api/provider) - Full API documentation
## Troubleshooting
Can't see the map? Please check [Frequently Asked Questions](/troubleshooting/common-issues).
---
## Source File: guide/core-concepts.md
- URL: https://react-naver-maps-kit.pages.dev/guide/core-concepts
- Local Path: packages/docs/guide/core-concepts.md
# Core Concept
This page explains the core architecture and operation of `react-naver-maps-kit`.
## Architecture Overview
```
┌─────────────────────────────────────────────────────────┐
│ NaverMapProvider │
│ ┌─────────────────────────────────────────────────┐ │
│ │ SDK Loading State │ │
│ │ idle → loading → ready │ │
│ │ ↘ error │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ NaverMap │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ Marker │ │ Circle │ │ InfoWindow │ ... │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## Provider pattern
### Why do you need a Provider?
Naver Map SDK is an external JavaScript library. To use it in your React app:
1. **SDK script loading** - Dynamically inserting `