A beautiful, customizable React map component built on top of Leaflet with Google Maps-style controls
npm install khmapsA beautiful, customizable React map component library built on top of Leaflet with Google Maps-style controls.
- πΊοΈ 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
``bash`
npm install khmaps leaflet react-leaflet
or
`bash`
yarn add khmaps leaflet react-leaflet
This library requires the following peer dependencies:
- react >= 18.0.0react-dom
- >= 18.0.0leaflet
- >= 1.9.0react-leaflet
- >= 4.0.0
`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
return (
{/ Layer Switcher /}
Components
$3
The main map container component.
`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 callbackHooks
$3
Hook for getting user's current location.
`tsx
const { position, error, loading } = useGeolocation({
fallback: [lat, lng]
});
`Options:
-
fallback: Coordinates - Fallback coordinates if geolocation failsReturns:
-
position: Coordinates | null - User's current position
- error: GeolocationPositionError | null - Geolocation error if any
- loading: boolean - Loading stateConstants
$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';
``MIT
Contributions are welcome! Please open an issue or submit a pull request.
For issues and questions, please open an issue on GitHub.