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

npm install khmaps leaflet react-leaflet

or

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

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 <div>Loading map...</div>;

  return (
    <div style={{ position: 'relative', width: '100%', height: '100vh' }}>
      <MapView
        center={position}
        tileUrl={MapLayer[selectedLayer]}
        zoom={13}
      >
        <LocationMarker position={position} />
        <ZoomControls />
        <CurrentLocationButton />
      </MapView>

      {/* Layer Switcher */}
      <div style={{ position: 'absolute', bottom: '1rem', left: '1rem', zIndex: 999 }}>
        <LayerSwitcher
          selectedLayer={selectedLayer}
          onLayerChange={setSelectedLayer}
        />
      </div>
    </div>
  );
}

Components

MapView

The main map container component.

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

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

ZoomControls

Zoom in/out buttons.

<ZoomControls />

CurrentLocationButton

Button to center map on user's current location.

<CurrentLocationButton
  onLocationFound={(coords) => console.log(coords)}
/>

Props:

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

LocationMarker

Visual marker showing user's current location.

<LocationMarker position={[lat, lng]} />

Props:

• position: Coordinates - Location to display marker

LayerSwitcher

UI control for switching between map layers.

<LayerSwitcher
  selectedLayer="Default"
  onLayerChange={(layer) => setSelectedLayer(layer)}
/>

Props:

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

Hooks

useGeolocation

Hook for getting user's current location.

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

MapLayer

Predefined map layer URLs:

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:

<MapView
  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:

import 'leaflet/dist/leaflet.css';

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

TypeScript

Full TypeScript support with exported types:

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.