### Install react-naver-maps

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Install the library using npm. React 19 or later is required.

```bash
npm install react-naver-maps
# React 19+ required
```

--------------------------------

### Uncontrolled NaverMap Example

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use this for initial map setup where the map manages its own state. Provides default values for center, zoom, and map type.

```tsx
import { Container, NaverMap, Marker } from 'react-naver-maps';

// Uncontrolled — initial values only, map manages state internally
function UncontrolledMap() {
  return (
    <Container style={{ width: '100%', height: '400px' }}>
      <NaverMap
        defaultCenter={{ lat: 37.5666, lng: 126.9784 }}
        defaultZoom={15}
        defaultMapTypeId="normal"
        minZoom={6}
        maxZoom={21}
        zoomControl
        scaleControl
      >
        <Marker defaultPosition={{ lat: 37.5666, lng: 126.9784 }} />
      </NaverMap>
    </Container>
  );
}
```

--------------------------------

### Marker Component Examples

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Demonstrates various ways to use the Marker component, including uncontrolled, controlled, draggable, custom icons, and animations. Markers can be conditionally rendered.

```tsx
import { useState } from 'react';
import { NaverMap, Marker, useNavermaps } from 'react-naver-maps';

function MarkerExample() {
  const navermaps = useNavermaps();
  const [position, setPosition] = useState(new navermaps.LatLng(37.5666, 126.9784));

  return (
    <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={15}> 
      {/* Uncontrolled marker */}
      <Marker defaultPosition={{ lat: 37.57, lng: 126.99 }} title="Seoul" />

      {/* Controlled draggable marker */}
      <Marker
        position={position}
        draggable
        animation={navermaps.Animation.BOUNCE}
        icon={{
          url: 'https://example.com/custom-icon.png',
          size: new navermaps.Size(24, 37),
          anchor: new navermaps.Point(12, 37),
        }}
        onClick={(e) => console.log('marker clicked', e.coord)}
        onDragend={(e) => setPosition(e.coord as naver.maps.LatLng)}
        onMouseover={() => console.log('hover')}
      />

      {/* Conditionally rendered marker — unmount removes from map */}
      {position.lat > 37 && (
        <Marker defaultPosition={{ lat: 37.56, lng: 126.97 }} zIndex={200} />
      )}
    </NaverMap>
  );
}
```

--------------------------------

### preloadNavermaps

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Starts loading the Naver Maps script before a `<NavermapsProvider>` renders. This is useful in routers to prefetch the script when hovering over a link and can be called outside React.

```APIDOC
## preloadNavermaps

Starts loading the Naver Maps script before a `<NavermapsProvider>` renders — useful in routers to prefetch the script when hovering over a link. Can be called outside React.

```tsx
import { preloadNavermaps } from 'react-naver-maps';

// Call during route hover or app init to preload
preloadNavermaps({ ncpKeyId: 'YOUR_NCP_KEY_ID' });

// With submodules
preloadNavermaps({ ncpKeyId: 'YOUR_NCP_KEY_ID', submodules: ['geocoder'] });
```
```

--------------------------------

### Component Structure for useMap()

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/guides/use-map.mdx

The useMap() hook is only functional within child components of <NaverMap>. This example shows a typical structure where MyControls, which uses useMap(), is a child of <NaverMap>.

```tsx
<Container style={{ width: '100%', height: '400px' }}>
  <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={15}>
    <MyControls /> {/* useMap() 사용 가능 */}
    <Marker position={{ lat: 37.5666, lng: 126.9784 }} />
  </NaverMap>
</Container>
```

--------------------------------

### Imperative NaverMap Control Example

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Access the underlying `naver.maps.Map` instance via a ref for imperative control. Useful for programmatically changing the map's view or state.

```tsx
import { useRef } from 'react';
import { Container, NaverMap } from 'react-naver-maps';

// Imperative control via ref
function ImperativeMap() {
  const mapRef = useRef<naver.maps.Map>(null);

  return (
    <Container style={{ width: '100%', height: '400px', position: 'relative' }}>
      <NaverMap ref={mapRef} defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={10} />
      <div style={{ position: 'absolute', top: 8, left: 8, zIndex: 100 }}>
        <button onClick={() => mapRef.current?.panTo({ lat: 35.1798, lng: 129.075 }, { duration: 500 }) }>
          Busan
        </button>
        <button onClick={() => mapRef.current?.morph({ lat: 33.3591, lng: 126.5344 }, 12) }>
          Jeju (zoom 12)
        </button>
        <button onClick={() => mapRef.current?.setZoom(mapRef.current.getZoom() + 1) }>
          Zoom In
        </button>
        <button onClick={() => mapRef.current?.fitBounds({
          south: 37.24, west: 131.86, north: 37.24, east: 131.88
        }) }>
          Dokdo
        </button>
      </div>
    </Container>
  );
}
```

--------------------------------

### Controlled NaverMap Example

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use this when React state needs to drive the map's center and zoom. Events like 'onCenterChanged' and 'onZoomChanged' update the state.

```tsx
import { useState } from 'react';
import { Container, NaverMap } from 'react-naver-maps';

// Controlled — React state drives center and zoom
function ControlledMap() {
  const [center, setCenter] = useState({ lat: 37.5666, lng: 126.9784 });
  const [zoom, setZoom] = useState(15);

  return (
    <>
      <Container style={{ width: '100%', height: '400px' }}>
        <NaverMap
          center={center}
          zoom={zoom}
          onCenterChanged={(c) => setCenter({ lat: c.y, lng: c.x })}
          onZoomChanged={(z) => setZoom(z)}
          onClick={(e) => console.log('clicked at', e.coord)}
          onIdle={() => console.log('map idle')}
          draggable
          scrollWheel
          disableDoubleClickZoom={false}
        />
      </Container>
      <button onClick={() => setCenter({ lat: 33.3591, lng: 126.5344 }) }>
        Go to Jeju
      </button>
    </>
  );
}
```

--------------------------------

### Preload Naver Maps Script

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use preloadNavermaps to start loading the Naver Maps script before rendering NavermapsProvider. This is useful for prefetching scripts, especially in routers. It can be called outside of React.

```tsx
import { preloadNavermaps } from 'react-naver-maps';

// Call during route hover or app init to preload
preloadNavermaps({ ncpKeyId: 'YOUR_NCP_KEY_ID' });

// With submodules
preloadNavermaps({ ncpKeyId: 'YOUR_NCP_KEY_ID', submodules: ['geocoder'] });
```

--------------------------------

### Get NaverMap Instance with useMap()

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/guides/use-map.mdx

Use the useMap() hook within a child component of <NaverMap> to get the current map instance. This allows for imperative control over map functionalities.

```tsx
import { useMap } from 'react-naver-maps';

function MyControls() {
  const map = useMap();

  return (
    <div>
      <button onClick={() => map.setZoom(map.getZoom() + 1)}>+</button>
      <button onClick={() => map.setZoom(map.getZoom() - 1)}>-</button>
    </div>
  );
}
```

--------------------------------

### Draw a Polyline on Naver Map

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use the Polyline component to draw a path defined by an array of coordinates. Supports custom start and end icons, stroke styling, and click events.

```tsx
import { NaverMap, Polyline, useNavermaps } from 'react-naver-maps';

function PolylineExample() {
  const navermaps = useNavermaps();

  const path = [
    new navermaps.LatLng(37.555, 126.97),
    new navermaps.LatLng(37.56, 126.975),
    new navermaps.LatLng(37.555, 126.98),
    new navermaps.LatLng(37.56, 126.985),
  ];

  return (
    <NaverMap defaultCenter={new navermaps.LatLng(37.558, 126.978)} defaultZoom={14}>
      <Polyline
        path={path}
        strokeColor="#0000FF"
        strokeWeight={3}
        strokeOpacity={0.8}
        startIcon={navermaps.PointingIcon.CIRCLE}
        endIcon={navermaps.PointingIcon.BLOCK_ARROW}
        endIconSize={10}
        clickable
        onClick={(e) => console.log('line clicked', e)}
      />
    </NaverMap>
  );
}
```

--------------------------------

### Get Current Map State

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/guides/use-map.mdx

Retrieve the current map's center coordinates, zoom level, and boundaries using methods like getCenter(), getZoom(), and getBounds() from the map instance obtained via useMap().

```tsx
function MapInfo() {
  const map = useMap();
  const [info, setInfo] = useState('');

  return (
    <div>
      <button
        onClick={() => {
          const center = map.getCenter();
          const zoom = map.getZoom();
          const bounds = map.getBounds();
          setInfo(`center: ${center}, zoom: ${zoom}, bounds: ${bounds}`);
        }}
      >
        현재 상태
      </button>
      {info && <pre>{info}</pre>}
    </div>
  );
}
```

--------------------------------

### Basic Usage

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/api-references/container.mdx

Demonstrates the fundamental usage of the Container component as a parent for NaverMap, setting basic dimensions.

```APIDOC
## Basic Usage

### Description
This example shows how to use the `Container` component as a parent for `NaverMap`, specifying its dimensions via CSS styles.

### Code
```tsx
import { Container as MapDiv, NaverMap } from 'react-naver-maps';

<MapDiv style={{ width: '100%', height: '400px' }}>
  <NaverMap />
</MapDiv>;
```
```

--------------------------------

### Initialize NavermapsProvider with Submodules

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Load additional Naver Maps modules like 'geocoder' or 'drawing' by passing an array to the submodules prop.

```tsx
import { NavermapsProvider } from 'react-naver-maps';

// With submodules
function AppWithSubmodules() {
  return (
    <NavermapsProvider ncpKeyId="YOUR_NCP_KEY_ID" submodules={['geocoder', 'drawing']}>
      <MyMap />
    </NavermapsProvider>
  );
}
```

--------------------------------

### Render Naver Maps InfoWindow Declaratively

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use the `open` prop for declarative control of the InfoWindow. Attach it to a marker using the `anchor` prop. The `content` prop accepts an HTML string.

```tsx
import { useState, useRef } from 'react';
import { NaverMap, Marker, InfoWindow, useNavermaps } from 'react-naver-maps';

// Declarative open/close with anchor
function InfoWindowExample() {
  const navermaps = useNavermaps();
  const [open, setOpen] = useState(false);
  const markerRef = useRef<naver.maps.Marker>(null);

  return (
    <NaverMap defaultCenter={new navermaps.LatLng(37.5666, 126.9784)} defaultZoom={15}>
      <Marker
        ref={markerRef}
        position={new navermaps.LatLng(37.5666, 126.9784)}
        onClick={() => setOpen((prev) => !prev)}
      />
      {open && (
        <InfoWindow
          content="<strong>Seoul City Hall</strong><br/>Jung-gu, Seoul"
          anchor={markerRef.current ?? undefined}
          maxWidth={200}
          backgroundColor="#fff"
          borderColor="#ddd"
          borderWidth={1}
          disableAutoPan={false}
          onClose={() => setOpen(false)}
        />
      )}
    </NaverMap>
  );
}
```

--------------------------------

### 기본 지도 표시 예제

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/examples/map-tutorial-1-simple.mdx

이 예제는 NavermapsProvider로 인증 키를 설정하고, Container로 지도 영역을 잡은 뒤 NaverMap을 렌더링하는 가장 기본적인 지도 표시 방법을 보여줍니다. Container는 position: relative인 div이며, Suspense를 포함하여 스크립트 로드를 자동으로 처리합니다.

```tsx
import React from "react";
import {
  NavermapsProvider,
  Container,
  NaverMap,
} from "react-navermaps";

export default function BasicMap() {
  return (
    <NavermapsProvider
      ncpClientId="YOUR_CLIENT_ID"
      error kiujs="YOUR_ERROR_KIJS"
    >
      <Container
        style={{
          width: "100%",
          height: "400px",
        }}
      >
        <NaverMap
          defaultCenter={{
            lat: 37.5666805,
            lng: 126.9784147,
          }}
          defaultZoom={12}
        />
      </Container>
    </NavermapsProvider>
  );
}
```

--------------------------------

### Loading Fallback UI

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/api-references/container.mdx

Shows how to specify a custom UI element to display while the Naver Maps scripts are loading using the `fallback` prop.

```APIDOC
## Loading Fallback UI

### Description
Utilize the `fallback` prop on the `Container` component to define custom content that will be displayed to the user during the Naver Maps script loading process.

### Code
```tsx
<Container
  style={{ width: '100%', height: '400px' }}
  fallback={<div>지도를 불러오는 중...</div>}
>
  <NaverMap />
</Container>
```
```

--------------------------------

### Server-Side Rendering (SSR) Considerations

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/api-references/container.mdx

Explains the behavior of the Container component during SSR and the requirement to call `useNavermaps()` within the Container.

```APIDOC
## Server-Side Rendering (SSR) Considerations

### Description
In SSR environments, the `Container` component initially renders only an outer div with height. The map itself is displayed after client-side hydration. It is crucial to call hooks like `useNavermaps()` exclusively within the `Container` component to ensure proper functionality.

### Usage Note
Ensure `useNavermaps()` is called within the `Container` component during SSR.
```

--------------------------------

### Initialize NavermapsProvider with Legacy Client ID

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use the legacy NCP client ID for authentication by passing it to the ncpClientId prop.

```tsx
import { NavermapsProvider } from 'react-naver-maps';

// Legacy NCP client ID
function AppLegacy() {
  return (
    <NavermapsProvider ncpClientId="YOUR_LEGACY_CLIENT_ID">
      <MyMap />
    </NavermapsProvider>
  );
}
```

--------------------------------

### Control Naver Maps InfoWindow Imperatively

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use a `ref` to imperatively control the `open()` and `close()` methods of the InfoWindow. The `content` prop accepts an HTML string.

```tsx
import { useState, useRef } from 'react';
import { NaverMap, Marker, InfoWindow, useNavermaps } from 'react-naver-maps';

// Imperative control via ref
function InfoWindowImperative() {
  const navermaps = useNavermaps();
  const infoRef = useRef<naver.maps.InfoWindow>(null);

  return (
    <NaverMap defaultCenter={new navermaps.LatLng(37.5666, 126.9784)} defaultZoom={15}>
      <InfoWindow
        ref={infoRef}
        content="<div style='padding:8px'>Hello!</div>"
        position={new navermaps.LatLng(37.5666, 126.9784)}
      />
      <button onClick={() => infoRef.current?.open(undefined as any)}>Open</button>
      <button onClick={() => infoRef.current?.close()}>Close</button>
    </NaverMap>
  );
}
```

--------------------------------

### useOverlay

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Connects a vanilla `naver.maps.OverlayView` subclass instance to the React lifecycle. It calls `factory()` once on mount and cleans up with `clearInstanceListeners` and `setMap(null)` on unmount. This hook is intended for building custom overlay components that extend `naver.maps.OverlayView`.

```APIDOC
## useOverlay

Connects a vanilla `naver.maps.OverlayView` subclass instance to the React lifecycle. Calls `factory()` once on mount and cleans up with `clearInstanceListeners` + `setMap(null)` on unmount. Use this hook when building custom overlay components that extend `naver.maps.OverlayView`.

```tsx
import { useRef } from 'react';
import { useMap, useNavermaps, useOverlay } from 'react-naver-maps';

// Custom overlay that extends naver.maps.OverlayView
function usePulsingMarker(position: naver.maps.LatLng) {
  const navermaps = useNavermaps();
  const map = useMap();

  const overlay = useOverlay(() => {
    class PulsingMarker extends navermaps.OverlayView {
      private _el: HTMLDivElement;
      constructor() {
        super();
        this._el = document.createElement('div');
        this._el.style.cssText = `
          width: 16px; height: 16px; border-radius: 50%;
          background: rgba(99,102,241,0.8);
          animation: pulse 1.5s infinite;
          position: absolute;
        `;
      }
      onAdd() { this.getPanes()!.overlayLayer.appendChild(this._el); }
      draw() {
        const proj = this.getProjection();
        const pt = proj.fromCoordToOffset(position);
        this._el.style.left = `${pt.x - 8}px`;
        this._el.style.top = `${pt.y - 8}px`;
      }
      onRemove() { this._el.parentNode?.removeChild(this._el); }
    }

    const instance = new PulsingMarker();
    instance.setMap(map);
    return instance;
  });

  return overlay;
}
```
```

--------------------------------

### Basic Container Usage

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/api-references/container.mdx

Use the Container component as a parent for NaverMap to render it within a specified DOM element. It includes Suspense for automatic script loading.

```tsx
import { Container as MapDiv, NaverMap } from 'react-naver-maps';

<MapDiv style={{ width: '100%', height: '400px' }}>
  <NaverMap />
</MapDiv>;
```

--------------------------------

### Initialize NavermapsProvider with NCP Key

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Provide the Naver Maps authentication key using NavermapsProvider at the app root. Supports ncpKeyId, ncpClientId, govClientId, and finClientId.

```tsx
import { NavermapsProvider } from 'react-naver-maps';

// Standard NCP key
function App() {
  return (
    <NavermapsProvider ncpKeyId="YOUR_NCP_KEY_ID">
      <MyMap />
    </NavermapsProvider>
  );
}
```

--------------------------------

### Render Function with Navermaps Namespace

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/api-references/container.mdx

Illustrates how to use a render function as a child of Container to access the `navermaps` namespace for advanced map configurations.

```APIDOC
## Render Function with Navermaps Namespace

### Description
Pass a render function as a child to the `Container`. This function receives the `navermaps` namespace as an argument, allowing direct access to its properties like `LatLng` for map initialization.

### Code
```tsx
<Container style={{ width: '100%', height: '400px' }}>
  {(navermaps) => (
    <NaverMap
      defaultCenter={new navermaps.LatLng(37.5666, 126.9784)}
      defaultZoom={15}
    />
  )}
</Container>
```
```

--------------------------------

### Move Map with panTo() and morph()

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/guides/use-map.mdx

Utilize the map instance obtained from useMap() to move the map. panTo() animates the map to a new center, while morph() can change both the center and zoom level simultaneously. Use panTo() for general movements, especially when only the center needs to change, as setCenter() can interrupt ongoing animations.

```tsx
function MoveButtons() {
  const map = useMap();
  const navermaps = useNavermaps();

  return (
    <div>
      <button
        onClick={() => map.panTo(new navermaps.LatLng(37.5666, 126.9784))}
      >
        서울시청으로 이동
      </button>
      <button
        onClick={() => map.morph(new navermaps.LatLng(33.359, 126.5344), 12)}
      >
        제주도로 이동 (줌 포함)
      </button>
    </div>
  );
}
```

--------------------------------

### Create Custom Overlay with useOverlay

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

The useOverlay hook connects a custom naver.maps.OverlayView subclass to the React lifecycle. It calls a factory function on mount and cleans up on unmount. Use this for building custom overlay components.

```tsx
import { useRef } from 'react';
import { useMap, useNavermaps, useOverlay } from 'react-naver-maps';

// Custom overlay that extends naver.maps.OverlayView
function usePulsingMarker(position: naver.maps.LatLng) {
  const navermaps = useNavermaps();
  const map = useMap();

  const overlay = useOverlay(() => {
    class PulsingMarker extends navermaps.OverlayView {
      private _el: HTMLDivElement;
      constructor() {
        super();
        this._el = document.createElement('div');
        this._el.style.cssText = `
          width: 16px; height: 16px; border-radius: 50%;
          background: rgba(99,102,241,0.8);
          animation: pulse 1.5s infinite;
          position: absolute;
        `;
      }
      onAdd() { this.getPanes()!.overlayLayer.appendChild(this._el); }
      draw() {
        const proj = this.getProjection();
        const pt = proj.fromCoordToOffset(position);
        this._el.style.left = `${pt.x - 8}px`;
        this._el.style.top = `${pt.y - 8}px`;
      }
      onRemove() { this._el.parentNode?.removeChild(this._el); }
    }

    const instance = new PulsingMarker();
    instance.setMap(map);
    return instance;
  });

  return overlay;
}
```

--------------------------------

### useNavermaps

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Returns the `naver.maps` namespace. This hook must be called inside a `<NavermapsProvider>` and a `<Suspense>` boundary. It suspends the component while the Naver Maps script is loading.

```APIDOC
## useNavermaps

Returns the `naver.maps` namespace. Must be called inside `<NavermapsProvider>` and inside a `<Suspense>` boundary (the `<Container>` component provides one automatically). Suspends the component while the Naver Maps script is loading.

```tsx
import { Suspense } from 'react';
import { NavermapsProvider, useNavermaps } from 'react-naver-maps';

function CoordInfo() {
  const navermaps = useNavermaps();
  const coord = new navermaps.LatLng(37.5666, 126.9784);

  return (
    <div>
      <p>Coord: {coord.toString()}</p>
      <p>Distance: {navermaps.getDistance(coord, new navermaps.LatLng(33.3591, 126.5344)).toFixed(0)}m</p>
    </div>
  );
}

function App() {
  return (
    <NavermapsProvider ncpKeyId="YOUR_NCP_KEY_ID">
      {/* Must be wrapped in Suspense when used outside Container */}
      <Suspense fallback={<p>Loading...</p>}>
        <CoordInfo />
      </Suspense>
    </NavermapsProvider>
  );
}
```
```

--------------------------------

### Render Custom React Content with CustomOverlay

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use CustomOverlay to render arbitrary React children at a specific geographic coordinate using a Portal. The 'anchor' prop can be used to offset the overlay relative to its position.

```tsx
import { useState } from 'react';
import { NaverMap, CustomOverlay, Marker, useNavermaps } from 'react-naver-maps';

function CustomOverlayExample() {
  const navermaps = useNavermaps();
  const [selected, setSelected] = useState<string | null>(null);

  const locations = [
    { id: 'city-hall', lat: 37.5666, lng: 126.9784, label: 'Seoul City Hall' },
    { id: 'gyeongbok', lat: 37.5796, lng: 126.977, label: 'Gyeongbokgung' },
  ];

  return (
    <NaverMap defaultCenter={new navermaps.LatLng(37.57, 126.978)} defaultZoom={14}>
      {locations.map((loc) => (
        <>
          <Marker
            key={`marker-${loc.id}`}
            position={{ lat: loc.lat, lng: loc.lng }}
            onClick={() => setSelected(loc.id === selected ? null : loc.id)}
          />
          {selected === loc.id && (
            <CustomOverlay
              key={`overlay-${loc.id}`}
              position={{ lat: loc.lat, lng: loc.lng }}
              anchor={new navermaps.Point(0, 40)}
              zIndex={100}
            >
              <div style={{
                background: 'white',
                border: '1px solid #ccc',
                borderRadius: '6px',
                padding: '6px 10px',
                fontSize: '13px',
                whiteSpace: 'nowrap',
                transform: 'translate(-50%, -100%)',
                boxShadow: '0 2px 6px rgba(0,0,0,0.2)',
              }}>
                {loc.label}
              </div>
            </CustomOverlay>
          )}
        </>
      ))}
    </NaverMap>
  );
}
```

--------------------------------

### Container with Loading Fallback

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/api-references/container.mdx

Specify a fallback UI to be displayed while the Naver Maps script is loading using the 'fallback' prop. This enhances user experience during script retrieval.

```tsx
<Container
  style={{ width: '100%', height: '400px' }}
  fallback={<div>지도를 불러오는 중...</div>}
>
  <NaverMap />
</Container>
```

--------------------------------

### Map Container with Fallback UI

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use the Container component to render the map, with a fallback UI displayed during script loading. Accepts standard div props and a fallback prop.

```tsx
import { NavermapsProvider, Container, NaverMap, useNavermaps } from 'react-naver-maps';

// Basic usage — built-in Suspense handles loading
function MapWithFallback() {
  return (
    <Container style={{ width: '100%', height: '400px' }} fallback={<div>Loading map...</div>}>
      <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={15} />
    </Container>
  );
}
```

--------------------------------

### Overlay Image on Naver Map with GroundOverlay

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

The GroundOverlay component allows you to overlay an image on the map within a specified geographical bounds. Changes to url or bounds require explicit recreation using React's key prop.

```tsx
import { NaverMap, GroundOverlay, useNavermaps } from 'react-naver-maps';

function GroundOverlayExample() {
  const navermaps = useNavermaps();

  const bounds = new navermaps.LatLngBounds(
    new navermaps.LatLng(37.55, 126.97),
    new navermaps.LatLng(37.58, 127.0),
  );

  return (
    <NaverMap defaultCenter={new navermaps.LatLng(37.565, 126.985)} defaultZoom={13}>
      <GroundOverlay
        url="https://example.com/overlay-image.png"
        bounds={bounds}
        opacity={0.7}
        clickable
        onClick={() => console.log('ground overlay clicked')}
      />
    </NaverMap>
  );
}
```

--------------------------------

### Access Naver Maps Namespace with useNavermaps

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

The useNavermaps hook returns the naver.maps namespace. It must be used within a NavermapsProvider and a Suspense boundary. It suspends rendering until the Naver Maps script is loaded.

```tsx
import { Suspense } from 'react';
import { NavermapsProvider, useNavermaps } from 'react-naver-maps';

function CoordInfo() {
  const navermaps = useNavermaps();
  const coord = new navermaps.LatLng(37.5666, 126.9784);

  return (
    <div>
      <p>Coord: {coord.toString()}</p>
      <p>Distance: {navermaps.getDistance(coord, new navermaps.LatLng(33.3591, 126.5344)).toFixed(0)}m</p>
    </div>
  );
}

function App() {
  return (
    <NavermapsProvider ncpKeyId="YOUR_NCP_KEY_ID">
      {/* Must be wrapped in Suspense when used outside Container */}
      <Suspense fallback={<p>Loading...</p>}>
        <CoordInfo />
      </Suspense>
    </NavermapsProvider>
  );
}
```

--------------------------------

### Container with Render Function

Source: https://github.com/zeakd/react-naver-maps/blob/main/website/src/content/docs/api-references/container.mdx

Pass a render function as a child to the Container to receive the 'navermaps' namespace as an argument. This allows for direct use of Naver Maps API functionalities within the render prop.

```tsx
<Container style={{ width: '100%', height: '400px' }}>
  {(navermaps) => (
    <NaverMap
      defaultCenter={new navermaps.LatLng(37.5666, 126.9784)}
      defaultZoom={15}
    />
  )}
</Container>
```

--------------------------------

### Map Container with Render Function

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Utilize a render function as children of the Container to access the navermaps namespace directly without an additional component.

```tsx
import { NavermapsProvider, Container, NaverMap, useNavermaps } from 'react-naver-maps';

// Render function — access navermaps namespace without extra component
function MapWithRenderFn() {
  return (
    <Container style={{ width: '100%', height: '400px' }}>
      {(navermaps) => (
        <NaverMap
          defaultCenter={new navermaps.LatLng(37.5666, 126.9784)}
          defaultZoom={15}
        />
      )}
    </Container>
  );
}
```

--------------------------------

### useMap

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Returns the `naver.maps.Map` instance from the nearest enclosing `<NaverMap>`. Use this hook for imperative operations not covered by props, such as `panTo`, `fitBounds`, or `getProjection`. It throws an error if called outside of a `<NaverMap>` component.

```APIDOC
## useMap

Returns the `naver.maps.Map` instance from the nearest enclosing `<NaverMap>`. Use it for imperative operations not covered by props (e.g., `panTo`, `fitBounds`, `getProjection`). Throws if called outside `<NaverMap>`.

```tsx
import { useMap, useNavermaps } from 'react-naver-maps';

function MapControls() {
  const map = useMap();
  const navermaps = useNavermaps();

  return (
    <div style={{ position: 'absolute', top: 8, right: 8, zIndex: 100 }}>
      <button onClick={() => map.setZoom(map.getZoom() + 1)}>+</button>
      <button onClick={() => map.setZoom(map.getZoom() - 1)}>−</button>
      <button onClick={() => map.panTo(new navermaps.LatLng(37.5666, 126.9784), { duration: 400 }) }>
        Seoul
      </button>
      <button onClick={() => {
        const c = map.getCenter();
        const z = map.getZoom();
        console.log(`center: ${c.lat()},${c.lng()} zoom: ${z}`);
      }}>
        Log State
      </button>
    </div>
  );
}

// Usage inside NaverMap
function MyMap() {
  return (
    <Container style={{ width: '100%', height: '400px', position: 'relative' }}>
      <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={14}>
        <MapControls />
      </NaverMap>
    </Container>
  );
}
```
```

--------------------------------

### Subscribe to Naver Maps KVO Property with useKVO

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Subscribes to a Naver Maps KVO property using useSyncExternalStore, triggering a re-render on property changes. Avoid for high-frequency KVOs like 'center' or 'bounds'; use event props instead. Safe for low-frequency properties like 'zoom' or 'mapTypeId'.

```tsx
import { useMap, useKVO } from 'react-naver-maps';

// Low-frequency KVO — zoom only fires when animation completes
function ZoomDisplay() {
  const map = useMap();
  const zoom = useKVO<number>(map, 'zoom');
  return <div>Zoom: {zoom}</div>;
}

function MapTypeDisplay() {
  const map = useMap();
  const mapTypeId = useKVO<string>(map, 'mapTypeId');
  return <div>Map type: {mapTypeId}</div>;
}

// ⚠️ High-frequency — avoid:
// const center = useKVO(map, 'center'); // fires every frame during drag
// ✅ Use event prop instead:
// <NaverMap onCenterChanged={(c) => setState(c)} />
```

--------------------------------

### Synchronize React Prop to Naver Maps KVO with useControlledKVO

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Synchronizes a React prop value to a Naver Maps KVO property by calling the KVO setter on each render. Skips initialization on the first render, skips if the prop value is undefined (enabling controlled/uncontrolled coexistence), and skips if the KVO value already matches the prop.

```tsx
import { useOverlay, useMap, useNavermaps, useControlledKVO } from 'react-naver-maps';

interface MyMarkerProps {
  position?: naver.maps.LatLng;
  opacity?: number;
  visible?: boolean;
}

function MyCustomMarker({ position, opacity, visible }: MyMarkerProps) {
  const navermaps = useNavermaps();
  const map = useMap();

  const marker = useOverlay(() =>
    new navermaps.Marker({
      map,
      position: position ?? new navermaps.LatLng(37.5666, 126.9784),
    })
  );

  // Sync props to KVO — undefined means uncontrolled (skip)
  useControlledKVO(marker!, 'position', position);
  useControlledKVO(marker!, 'visible', visible);

  return null;
}
```

--------------------------------

### Draw a Circle on Naver Map

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Renders a circle on the map defined by `center` and `radius`. Supports styling and mouse events. The `radius` can be controlled dynamically.

```tsx
import { useState } from 'react';
import { NaverMap, Circle, useNavermaps } from 'react-naver-maps';

function CircleExample() {
  const navermaps = useNavermaps();
  const [radius, setRadius] = useState(500);

  return (
    <NaverMap defaultCenter={new navermaps.LatLng(37.5666, 126.9784)} defaultZoom={14}>
      <Circle
        center={new navermaps.LatLng(37.5666, 126.9784)}
        radius={radius}
        strokeColor="#5347AA"
        strokeWeight={2}
        strokeOpacity={0.8}
        fillColor="#E4E0FF"
        fillOpacity={0.3}
        clickable
        onClick={() => setRadius((r) => r + 100)}
        onMouseover={() => console.log('circle hover')}
      />
    </NaverMap>
  );
}
```

--------------------------------

### Draw a Rectangle on Naver Map

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Renders a rectangle on the map defined by `bounds`. Supports styling and mouse events. The `bounds` prop expects an object with `south`, `west`, `north`, and `east` coordinates.

```tsx
import { NaverMap, Rectangle } from 'react-naver-maps';

function RectangleExample() {
  return (
    <NaverMap defaultCenter={{ lat: 37.565, lng: 126.975 }} defaultZoom={13}>
      <Rectangle
        bounds={{ south: 37.56, west: 126.97, north: 37.57, east: 126.98 }}
        strokeColor="#FF0000"
        strokeWeight={2}
        strokeOpacity={1}
        fillColor="#FF0000"
        fillOpacity={0.15}
        clickable
        onClick={(e) => console.log('rectangle clicked', e)}
      />
    </NaverMap>
  );
}
```

--------------------------------

### Attach Naver Maps Event Listener with useListener

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Safely attaches a native Naver Maps event listener. It uses the useEffectEvent pattern to avoid re-subscribing when an inline callback changes, only re-subscribing when the target or eventName changes.

```tsx
import { useRef, useState } from 'react';
import { useMap, useListener } from 'react-naver-maps';

function IdleTracker() {
  const map = useMap();
  const [idleCount, setIdleCount] = useState(0);

  // Inline function is safe — does not cause re-subscription on each render
  useListener(map, 'idle', () => setIdleCount((n) => n + 1));

  return <div>Map settled {idleCount} time(s)</div>;
}

function MarkerDragTracker() {
  const markerRef = useRef<naver.maps.Marker>(null);
  const [lastPos, setLastPos] = useState('');

  useListener(markerRef.current, 'dragend', (e: unknown) => {
    const event = e as naver.maps.PointerEvent;
    setLastPos(`${event.coord.y.toFixed(5)}, ${event.coord.x.toFixed(5)}`);
  });

  return <div>Last drag position: {lastPos}</div>;
}
```

--------------------------------

### Draw a Polygon on Naver Map

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Renders a polygon on the map defined by `paths`. Supports controlled geometry, styling, and mouse events. The `paths` prop is an array of coordinate arrays, where each inner array represents a ring.

```tsx
import { NaverMap, Polygon } from 'react-naver-maps';

function PolygonExample() {
  const polygonPaths = [
    [
      { lat: 37.57, lng: 126.975 },
      { lat: 37.575, lng: 126.985 },
      { lat: 37.565, lng: 126.985 },
    ],
  ];

  return (
    <NaverMap defaultCenter={{ lat: 37.57, lng: 126.98 }} defaultZoom={14}>
      <Polygon
        paths={polygonPaths}
        strokeColor="#00AA00"
        strokeWeight={2}
        fillColor="#00FF00"
        fillOpacity={0.2}
        clickable
        onClick={(e) => console.log('polygon clicked', e.coord)}
      />
    </NaverMap>
  );
}
```

--------------------------------

### Access Naver Map Instance with useMap

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

The useMap hook retrieves the naver.maps.Map instance from the nearest NaverMap component. Use it for imperative map operations like panTo or fitBounds. It throws an error if called outside of a NaverMap.

```tsx
import { useMap, useNavermaps } from 'react-naver-maps';

function MapControls() {
  const map = useMap();
  const navermaps = useNavermaps();

  return (
    <div style={{ position: 'absolute', top: 8, right: 8, zIndex: 100 }}>
      <button onClick={() => map.setZoom(map.getZoom() + 1)}>+</button>
      <button onClick={() => map.setZoom(map.getZoom() - 1)}>−</button>
      <button onClick={() => map.panTo(new navermaps.LatLng(37.5666, 126.9784), { duration: 400 })}>
        Seoul
      </button>
      <button onClick={() => {
        const c = map.getCenter();
        const z = map.getZoom();
        console.log(`center: ${c.lat()},${c.lng()} zoom: ${z}`);
      }}>
        Log State
      </button>
    </div>
  );
}

// Usage inside NaverMap
function MyMap() {
  return (
    <Container style={{ width: '100%', height: '400px', position: 'relative' }}>
      <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={14}>
        <MapControls />
      </NaverMap>
    </Container>
  );
}
```

--------------------------------

### Draw an Ellipse on Naver Map

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Renders an ellipse on the map defined by `bounds`. Accepts the same stroke/fill props as other shape components and supports mouse events. The `bounds` prop expects an object with `south`, `west`, `north`, and `east` coordinates.

```tsx
import { NaverMap, Ellipse } from 'react-naver-maps';

function EllipseExample() {
  return (
    <NaverMap defaultCenter={{ lat: 37.565, lng: 126.975 }} defaultZoom={13}>
      <Ellipse
        bounds={{ south: 37.555, west: 126.965, north: 37.575, east: 126.99 }}
        strokeColor="#9333ea"
        strokeWeight={2}
        fillColor="#d8b4fe"
        fillOpacity={0.4}
        clickable
        onMouseover={() => console.log('hover')}
      />
    </NaverMap>
  );
}
```

--------------------------------

### Display Cadastral Layer with Toggle

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Use the CadastralLayer component to display land parcel boundaries. Mount or unmount the component to show or hide the layer.

```tsx
import { useState } from 'react';
import { NaverMap, CadastralLayer } from 'react-naver-maps';

function CadastralLayerExample() {
  const [show, setShow] = useState(false);

  return (
    <>
      <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={15}>
        {show && <CadastralLayer />}
      </NaverMap>
      <button onClick={() => setShow((v) => !v)}>Toggle Cadastral</button>
    </>
  );
}
```

--------------------------------

### CadastralLayer

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Displays the cadastral (land parcel boundary) layer on the map. This component has no configuration props and can be shown or hidden by mounting or unmounting it.

```APIDOC
## CadastralLayer

Displays the cadastral (land parcel boundary) layer on the map. No configuration props; mount/unmount to show/hide.

```tsx
import { useState } from 'react';
import { NaverMap, CadastralLayer } from 'react-naver-maps';

function CadastralLayerExample() {
  const [show, setShow] = useState(false);

  return (
    <>
      <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={15}>
        {show && <CadastralLayer />}
      </NaverMap>
      <button onClick={() => setShow((v) => !v)}>Toggle Cadastral</button>
    </>
  );
}
```
```

--------------------------------

### Toggle Naver Street View Layer

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

The StreetLayer component displays the Naver street view (panorama) layer. It has no configuration props and can be removed by unmounting the component.

```tsx
import { useState } from 'react';
import { NaverMap, StreetLayer } from 'react-naver-maps';

function StreetLayerExample() {
  const [show, setShow] = useState(false);

  return (
    <>
      <NaverMap defaultCenter={{ lat: 37.5666, lng: 126.9784 }} defaultZoom={15}>
        {show && <StreetLayer />}
      </NaverMap>
      <button onClick={() => setShow((v) => !v)}>Toggle Street View</button>
    </>
  );
}
```

--------------------------------

### Map Container with Custom Inner Style

Source: https://context7.com/zeakd/react-naver-maps/llms.txt

Apply custom styling to the internal div element of the map container using the innerStyle prop.

```tsx
import { NavermapsProvider, Container, NaverMap, useNavermaps } from 'react-naver-maps';

// Custom inner div style
function MapCustomInner() {
  return (
    <Container
      style={{ width: '800px', height: '600px' }}
      innerStyle={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%' }}
    >
      <NaverMap />
    </Container>
  );
}
```