Beautiful map components. 100% Free, Zero config, one command setup.
TypeScript
import {
DocsLayout,
DocsSection,
DocsCode,
DocsLink,
DocsNote,
} from "../_components/docs";
import { ComponentPreview } from "../_components/component-preview";
import { AdvancedUsageExample } from "../_components/examples/advanced-usage-example";
import { CustomLayerExample } from "../_components/examples/custom-layer-example";
import { LayerMarkersExample } from "../_components/examples/layer-markers-example";
import { CodeBlock } from "../_components/code-block";
import { getExampleSource } from "../_components/get-example-source";
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Advanced",
};
const refCode = `import { Map, type MapRef } from "@/components/ui/map";
import { useRef } from "react";
function MyMapComponent() {
const mapRef = useRef<MapRef>(null);
const handleFlyTo = () => {
// Access the MapLibre GL map instance via ref
mapRef.current?.flyTo({ center: [-74, 40.7], zoom: 12 });
};
return (
<>
<button onClick={handleFlyTo}>Fly to NYC</button>
<Map ref={mapRef} center={[-74, 40.7]} zoom={10} />
</>
);
}`;
const useMapCode = `import { Map, useMap } from "@/components/ui/map";
import { useEffect } from "react";
// For child components inside Map, use the useMap hook
function MapEventListener() {
const { map, isLoaded } = useMap();
useEffect(() => {
if (!map || !isLoaded) return;
const handleClick = (e) => {
console.log("Clicked at:", e.lngLat);
};
map.on("click", handleClick);
return () => map.off("click", handleClick);
}, [map, isLoaded]);
return null;
}
// Usage
<Map center={[-74, 40.7]} zoom={10}>
<MapEventListener />
</Map>`;
export default function AdvancedPage() {
const advancedSource = getExampleSource("advanced-usage-example.tsx");
const customLayerSource = getExampleSource("custom-layer-example.tsx");
const layerMarkersSource = getExampleSource("layer-markers-example.tsx");
return (
<DocsLayout
title="Advanced"
description="Access the underlying MapLibre GL instance for advanced customization."
prev={{ title: "Clusters", href: "/docs/clusters" }}
>
<DocsSection>
<p>
Access the underlying MapLibre GL map instance to use any feature from
the MapLibre GL JS API. You can use either a <DocsCode>ref</DocsCode>{" "}
or the <DocsCode>useMap</DocsCode> hook.
</p>
</DocsSection>
<DocsNote>
<strong>Tip:</strong> Check the{" "}
<DocsLink
href="https://maplibre.org/maplibre-gl-js/docs/API/classes/Map/"
external
>
MapLibre GL JS documentation
</DocsLink>{" "}
for the full list of available methods and events.
</DocsNote>
<DocsSection title="Using a Ref">
<p>
The simplest way to access the map instance. Use a{" "}
<DocsCode>ref</DocsCode> to call map methods from event handlers or
effects.
</p>
<CodeBlock code={refCode} />
</DocsSection>
<DocsSection title="Using the Hook">
<p>
For child components rendered inside <DocsCode>Map</DocsCode>, use the{" "}
<DocsCode>useMap</DocsCode> hook to access the map instance and listen
to events.
</p>
<CodeBlock code={useMapCode} />
</DocsSection>
<DocsSection title="Example: Custom Controls">
<p>
This example shows how to create custom controls that manipulate the
map's pitch and bearing, and listen to map events to display
real-time values.
</p>
<ComponentPreview code={advancedSource}>
<AdvancedUsageExample />
</ComponentPreview>
</DocsSection>
<DocsSection title="Example: Custom GeoJSON Layer">
<p>
Add custom GeoJSON data as layers with fill and outline styles. This
example shows NYC parks with hover interactions.
</p>
<ComponentPreview code={customLayerSource}>
<CustomLayerExample />
</ComponentPreview>
</DocsSection>
<DocsSection title="Example: Markers via Layers">
<p>
When displaying hundreds or thousands of markers, use GeoJSON layers
instead of DOM-based <DocsCode>MapMarker</DocsCode> components. This
approach renders markers on the WebGL canvas, providing significantly
better performance.
</p>
<ComponentPreview code={layerMarkersSource}>
<LayerMarkersExample />
</ComponentPreview>
</DocsSection>
<DocsSection title="Extend to Build">
<p>You can extend this to build custom features like:</p>
<ul>
<li>
<strong>Real-time tracking</strong> - Live location updates for
delivery, rides, or fleet management
</li>
<li>
<strong>Geofencing</strong> - Trigger actions when users enter or
leave specific areas
</li>
<li>
<strong>Heatmaps</strong> - Visualize density data like population,
crime, or activity hotspots
</li>
<li>
<strong>Drawing tools</strong> - Let users draw polygons, lines, or
place markers for custom areas
</li>
<li>
<strong>3D buildings</strong> - Extrude building footprints for
urban visualization
</li>
<li>
<strong>Animations</strong> - Animate markers along routes or create
fly-through experiences
</li>
<li>
<strong>Custom data layers</strong> - Overlay weather, traffic, or
satellite imagery
</li>
</ul>
</DocsSection>
</DocsLayout>
);
}