# geo-korea

> A flexible library for visualizing data on South Korea's map

Latest version **1.0.7** (published 2026-03-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install geo-korea
pnpm add geo-korea
yarn add geo-korea
bun add geo-korea
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2026-03-12 |
| First published | 2025-01-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 146.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | mniii |
| Maintainers | bennykim |
| Keywords | d3, map, korea, visualization |

## Links

- npm: https://www.npmjs.com/package/geo-korea
- Repository: https://github.com/bennykim/geo-korea
- Homepage: https://github.com/bennykim/geo-korea#readme
- Issues: https://github.com/bennykim/geo-korea/issues
- npm.io page: https://npm.io/package/geo-korea

## Dependencies (3)

- [d3](https://npm.io/package/d3.md) ^7.9.0
- [d3-geo](https://npm.io/package/d3-geo.md) ^3.1.1
- [topojson-client](https://npm.io/package/topojson-client.md) ^3.1.0

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 1.0.7 (latest) — 2026-03-12
- 1.0.6 — 2025-01-23
- 1.0.5 — 2025-01-21
- 1.0.4 — 2025-01-19
- 1.0.3 — 2025-01-19
- 1.0.2 — 2025-01-18
- 1.0.1 — 2025-01-16
- 1.0.0 — 2025-01-16

## README

# Geo Korea

Interactive map visualization library for Korea using TopoJSON data, built with D3.js. This library provides a flexible and customizable way to create interactive maps of South Korea with features like region highlighting, custom markers, and smooth animations.

### 🚀 [Live Demo](https://geo-korea.netlify.app)

## Features

- 🗺️ Interactive region visualization with hover and click effects
- 📍 Customizable point markers with tooltips
- 🔍 Smooth zoom in/out and region focus transitions
- 🎨 Comprehensive theming system with dark mode support
- 🎯 Custom TopoJSON data support
- ⚛️ React component support
- 🔄 TypeScript support with full type definitions

## Installation

```bash
npm install geo-korea
# or
yarn add geo-korea
# or
pnpm add geo-korea
```

## Usage

### Basic Usage

#### JavaScript

The simplest way to create a map is to just provide a container ID:

```javascript
// Most basic usage - all options will be set to defaults
const GeoKoreaRenderer = new GeoKoreaInitializer();
const map = await GeoKoreaRenderer.createMap("map-container");
```

#### React

Using React, you can create a map with a ref:

```typescript
import React, { useEffect, useRef } from "react";
import { GeoKoreaInitializer } from "geo-korea";

const App: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (containerRef.current) {
      // Most basic usage - all options will be set to defaults
      const GeoKoreaRenderer = new GeoKoreaInitializer();
      const map = GeoKoreaRenderer.createMap(containerRef.current);

      return () => {
        map.destroy();
      };
    }
  }, []);

  return <div ref={containerRef} />;
};

export default App;
```

### Adding Options

You can enhance the map with various options:

```javascript
const GeoKoreaRenderer = new GeoKoreaInitializer();
const map = await GeoKoreaRenderer.createMap("map-container", {
  points: [
    {
      name: "Seoul City Hall",
      region: "Capital Area",
      location: "Seoul Metropolitan City",
      coordinates: [37.5666805, 126.9784147],
      type: "City Hall",
    },
  ],
  onRegionClick: (name) => console.log(`Clicked region: ${name}`),
});
```

### React Component

```typescript
import React, { useEffect, useRef } from "react";
import { GeoKoreaInitializer } from "geo-korea";

const Map: React.FC = () => {
  const mapContainerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (mapContainerRef.current) {
      const GeoKoreaRenderer = new GeoKoreaInitializer();
      const map = GeoKoreaRenderer.createMap(mapContainerRef.current, {
        points: [
          {
            name: "Seoul City Hall",
            region: "Capital Area",
            location: "Seoul Metropolitan City",
            coordinates: [37.5666805, 126.9784147],
            type: "City Hall",
          },
        ],
        onRegionClick: (name) => console.log(`Clicked region: ${name}`),
      });

      return () => {
        map.destroy();
      };
    }
  }, []);

  return <div ref={mapContainerRef} />;
};
```

## Configuration

### Auto-Calculated Values & Default Colors

When you create a map without options, the library will:

1. **Auto-Calculate**:

   - `width` and `height`: Automatically set based on the container size
   - `center` and `scale`: Automatically adjusted to fit the map perfectly within the container

2. **Default Colors**:

```javascript
const defaultColors = {
  region: "#2A2D35",
  regionHover: "#3F4046",
  point: "#5EEAD4",
  pointHover: "#6366F1",
  selected: "#6366F1",
  border: "#4A4B50",
};
```

### Available Options

#### MapOptions Interface

```typescript
type MapOptions = {
  width?: number; // Width of the map container
  height?: number; // Height of the map container
  center?: [number, number]; // Center coordinates [longitude, latitude]
  scale?: number; // Map scale (0.5 to 8)
  points?: Point[]; // Array of point markers
  colors?: ColorOptions; // Custom color theme
  onRegionClick?: (name: string) => void; // Region click handler
  tooltipRenderer?: (point: Point) => string; // Custom tooltip renderer
};
```

#### Point Interface

```typescript
type Point = {
  type: string; // Point type (e.g., "city", "landmark")
  name: string; // Point name
  region: string; // Region name
  location: string; // Location description
  coordinates: [number, number]; // [latitude, longitude]
  radius?: number; // Point size (default: 3)
  color?: string; // Custom point color
};
```

#### ColorOptions Interface

```typescript
type ColorOptions = {
  region?: string; // Default region color
  regionHover?: string; // Region hover color
  point?: string; // Default point marker color
  pointHover?: string; // Point marker hover color
  selected?: string; // Selected region color
  border?: string; // Region border color
};
```

## Advanced Features

### Custom TopoJSON Data

```typescript
const map = await GeoKoreaRenderer.createMap("map-container", {
  topoJsonPath: "/path/to/custom-map-data.json",
});
```

### Custom Tooltip Renderer

```typescript
const map = await GeoKoreaRenderer.createMap("map-container", {
  tooltipRenderer: (point) => {
    return `
      <div>
        <strong>${point.name}</strong>
        <p>${point.location}</p>
      </div>
    `;
  },
});
// or
// using React components
const map = GeoKoreaRenderer.createMap(mapContainerRef.current, {
  tooltipRenderer: (point) => {
    return `
      <div>
        <strong>${point.name}</strong>
        <p>${point.location}</p>
      </div>
    `;
  },
}
```

### Instance Methods

The `createMap` method returns a GeoKoreaInstance with the following methods:

```typescript
type GeoKoreaInstance = {
  map: GeoKorea; // Access to the underlying map instance
  destroy: () => void; // Clean up resources
  updatePoints: (points: Point[]) => void; // Update point markers
  setTopoData: (topoData: any, objectName: string) => void; // Update map data
};
```

## License

MIT © [MNIII]

---
_Source: https://npm.io/package/geo-korea · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._