KHMaps

A beautiful, customizable React map component library built on top of Leaflet with Google Maps-style controls.

Features

- 🗺️ Multiple Map Layers - Default, Roadmap, Satellite, and Hybrid views
- 📍 Geolocation Support - Automatic user location detection with visual marker
- 🎨 Beautiful UI - Google Maps-inspired controls and layer switcher
- 📱 Responsive - Works seamlessly on desktop and mobile
- 🎯 TypeScript - Full TypeScript support with type definitions
- ⚡ Lightweight - Minimal dependencies
- 🔧 Customizable - Easy to customize and extend

Installation

``bash
npm install khmaps leaflet react-leaflet
`

or

`bash
yarn add khmaps leaflet react-leaflet
`

Prerequisites

This library requires the following peer dependencies:

- react >= 18.0.0
- react-dom >= 18.0.0
- leaflet >= 1.9.0
- react-leaflet >= 4.0.0

Quick Start

`tsx
import { MapView, ZoomControls, LayerSwitcher, CurrentLocationButton, LocationMarker, useGeolocation } from 'khmaps';
import { MapLayer } from 'khmaps';

function MyMap() {
const [selectedLayer, setSelectedLayer] = useState('Default');
const { position, loading } = useGeolocation({
fallback: [11.5564, 104.9282] // Phnom Penh
});

if (loading || !position) return

`tsx
center={[lat, lng]}
zoom={13}
tileUrl="https://..."
subdomains={['a', 'b', 'c']}
attribution="Map data"
>
{/ Map children /}

`

Props:
- center: Coordinates - Map center coordinates [lat, lng]
- zoom?: number - Initial zoom level (default: 13)
- tileUrl: string - Tile layer URL
- subdomains?: string[] - Tile server subdomains
- attribution?: string - Map attribution text
- children?: React.ReactNode - Map controls and markers

$3

Zoom in/out buttons.

`tsx

`

$3

Button to center map on user's current location.

`tsx
onLocationFound={(coords) => console.log(coords)}
/>
`

Props:
- onLocationFound?: (coords: Coordinates) => void - Callback when location is found

$3

Visual marker showing user's current location.

`tsx

`

Props:
- position: Coordinates - Location to display marker

$3

UI control for switching between map layers.

`tsx
selectedLayer="Default"
onLayerChange={(layer) => setSelectedLayer(layer)}
/>
`

Props:
- selectedLayer: MapLayerType - Currently selected layer
- onLayerChange: (layer: MapLayerType) => void - Layer change callback

Hooks

$3

Hook for getting user's current location.

`tsx
const { position, error, loading } = useGeolocation({
fallback: [lat, lng]
});
`

Options:
- fallback: Coordinates - Fallback coordinates if geolocation fails

Returns:
- position: Coordinates | null - User's current position
- error: GeolocationPositionError | null - Geolocation error if any
- loading: boolean - Loading state

Constants

$3

Predefined map layer URLs:

`tsx
import { MapLayer } from 'khmaps';

console.log(MapLayer.Default); // CartoDB Light
console.log(MapLayer.Roadmap); // OpenStreetMap
console.log(MapLayer.Satellite); // ArcGIS World Imagery
console.log(MapLayer.Hybrid); // OpenTopoMap
`

Custom Map Layers

You can provide your own tile URLs:

`tsx
center={position}
tileUrl="https://your-custom-tiles/{z}/{x}/{y}.png"
subdomains={['a', 'b', 'c']}
/>
`

Styling

The components come with default styles. Make sure to import Leaflet CSS:

`tsx
import 'leaflet/dist/leaflet.css';
`

You can customize the appearance using Tailwind CSS classes or custom CSS.

TypeScript

Full TypeScript support with exported types:

`tsx
import type { Coordinates, MapLayerType, MapLayerConfig } from 'khmaps';
``

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions, please open an issue on GitHub.