Hooks

React hooks for controlling map components and accessing the Mapbox GL instance.

Available Hooks

These hooks provide programmatic control over map components and access to the underlying Mapbox GL instance.

useMap

Access the Mapbox GL instance and loading state

Used with Map

Updated

useRasterVideoControl

Control video layer playback with play, pause, and toggle

Used with MapRasterVideo

useLineAnimatedControl

Control animated line playback state

Used with MapLineAnimated

useMarkerAnimatedControl

Control animated marker playback state

Used with MapMarkerAnimated

useCameraFollowControl

Control camera follow animation playback

Used with MapCameraFollow

New

useArcAnimatedControl

Control animated arc playback state

Used with MapArcAnimated

New

useFootprintControl

Control animated footprint start and reset

Used with MapAnimatedFootprint

New

useCycloneControl

Control cyclone animation, intensity, scale, and rotation speed

Used with MapCyclone

New

useExplosionControl

Trigger and reset explosion effects

Used with MapExplosion

New

useFireControl

Control fire animation and intensity

Used with MapFire

New

useLightningControl

Trigger lightning strike effects

Used with MapLightning

New

useMeteorControl

Control meteor animation and track impact phases

Used with MapMeteor

New

useSandstormControl

Control sandstorm animation and intensity

Used with MapSandstorm

New

useSnowControl

Control snow animation and intensity

Used with MapSnow

New

useSteamControl

Control steam animation and intensity

Used with MapSteam

New

useTsunamiControl

Control tsunami animation and track wave phases

Used with MapTsunami

useMap

Access the Mapbox GL map instance and loading state. Must be used within a Map component.

import { useMap } from "@/registry/map";

const MyComponent = () => {
  const { map, isLoaded } = useMap();

  const flyToLocation = () => {
    if (!map) return;

    map.flyTo({
      center: [-74.006, 40.7128],
      zoom: 14,
    });
  };

  return (
    <button onClick={flyToLocation} disabled={!isLoaded}>
      Fly to NYC
    </button>
  );
};

Return Value	Type	Description
`map`	mapboxgl.Map \| null	The Mapbox GL map instance
`isLoaded`	boolean	Whether the map has finished loading

useRasterVideoControl

Control video layer playback. Pass the layer ID to control a specific MapRasterVideo component.

import { useRasterVideoControl } from "@/registry/map";

const VideoControls = () => {
  const { play, pause, toggle, isPlaying } = useRasterVideoControl("my-video-layer");

  return (
    <div className="flex gap-2">
      <button onClick={play}>Play</button>
      <button onClick={pause}>Pause</button>
      <button onClick={toggle}>
        {isPlaying ? "Pause" : "Play"}
      </button>
    </div>
  );
};

Parameter	Type	Description
`layerId`	string	The ID of the video layer to control

Return Value	Type	Description
`play`	() => void	Start video playback
`pause`	() => void	Pause video playback
`toggle`	() => void	Toggle between play and pause
`isPlaying`	boolean	Current playback state

useLineAnimatedControl

Control animated line playback state. Use with MapLineAnimated component.

import { useLineAnimatedControl, MapLineAnimated } from "@/registry/map";

const AnimatedRoute = () => {
  const { isPlaying, start, stop, toggle } = useLineAnimatedControl();

  return (
    <>
      <MapLineAnimated
        id="route"
        path={routePath}
        autoStart={isPlaying}
      />
      <button onClick={toggle}>
        {isPlaying ? "Stop" : "Start"} Animation
      </button>
    </>
  );
};

Return Value	Type	Description
`start`	() => void	Start the animation
`stop`	() => void	Stop the animation
`toggle`	() => void	Toggle animation state
`isPlaying`	boolean	Current animation state

useMarkerAnimatedControl

Control animated marker playback state. Use with MapMarkerAnimated component.

import { useMarkerAnimatedControl, MapMarkerAnimated } from "@/registry/map";

const AnimatedMarker = () => {
  const { isPlaying, start, stop, toggle } = useMarkerAnimatedControl();

  return (
    <>
      <MapMarkerAnimated
        id="marker"
        coordinates={pathCoordinates}
        autoStart={isPlaying}
      />
      <button onClick={toggle}>
        {isPlaying ? "Stop" : "Start"} Marker
      </button>
    </>
  );
};

Return Value	Type	Description
`start`	() => void	Start the animation
`stop`	() => void	Stop the animation
`toggle`	() => void	Toggle animation state
`isPlaying`	boolean	Current animation state

useCameraFollowControl

Control camera follow animation playback. Use with MapCameraFollow component.

import { useCameraFollowControl, MapCameraFollow, MapLine } from "@/registry/map";

const CameraFollow = () => {
  const { isPlaying, start, stop, toggle } = useCameraFollowControl();

  return (
    <>
      <MapLine coordinates={route} color="#3b82f6" width={4} />
      <MapCameraFollow
        path={route}
        autoStart={isPlaying}
        onComplete={stop}
        marker
      />
      <button onClick={toggle}>
        {isPlaying ? "Pause" : "Fly Along Route"}
      </button>
    </>
  );
};

Return Value	Type	Description
`start`	() => void	Start the camera animation
`stop`	() => void	Stop the camera animation
`toggle`	() => void	Toggle animation state
`isPlaying`	boolean	Current animation state

useArcAnimatedControl

Control animated arc playback state. Use with MapArcAnimated component.

import { useArcAnimatedControl, MapArcAnimated } from "@/registry/map";

const AnimatedArc = () => {
  const { isPlaying, start, stop, toggle } = useArcAnimatedControl();

  return (
    <>
      <MapArcAnimated
        id="arc"
        origin={[-74.006, 40.7128]}
        destination={[2.3522, 48.8566]}
      />
      <button onClick={toggle}>
        {isPlaying ? "Stop" : "Start"} Arc
      </button>
    </>
  );
};

Return Value	Type	Description
`start`	() => void	Start the animation
`stop`	() => void	Stop the animation
`toggle`	() => void	Toggle animation state
`isPlaying`	boolean	Current animation state

useFootprintControl

Control animated footprint start and reset. Returns null until the component with the matching ID mounts.

import { useFootprintControl, MapAnimatedFootprint } from "@/registry/map";

const FootprintControls = () => {
  const control = useFootprintControl("my-footprint");

  return (
    <>
      <MapAnimatedFootprint
        id="my-footprint"
        path={walkingPath}
        autoStart={false}
      />
      <button onClick={control?.start} disabled={control?.isActive}>
        Start Walking
      </button>
      <button onClick={control?.reset} disabled={!control?.isActive}>
        Reset
      </button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the footprint component to control

Return Value	Type	Description
`start`	() => void	Start the footprint animation
`reset`	() => void	Reset and hide all footprint steps
`isActive`	boolean	Whether the animation is currently active

useCycloneControl

Control cyclone animation, intensity, scale, and rotation speed. Returns null until the component with the matching ID mounts.

import { useCycloneControl, MapCyclone } from "@/registry/map";

const Cyclone = () => {
  const control = useCycloneControl("my-cyclone");

  return (
    <>
      <MapCyclone id="my-cyclone" coordinates={[139.6917, 35.6895]} />
      <button onClick={control?.isActive ? control.stop : control?.start}>
        {control?.isActive ? "Stop" : "Start"} Cyclone
      </button>
      <button onClick={() => control?.setIntensity(1.5)}>
        High Intensity
      </button>
      <button onClick={() => control?.setRotationSpeed(3)}>
        Fast Spin
      </button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the cyclone component to control

Return Value	Type	Description
`start`	() => void	Start the cyclone animation
`stop`	() => void	Stop the cyclone animation
`setIntensity`	(intensity: number) => void	Set the cyclone intensity
`setScale`	(scale: number, instant?: boolean) => void	Set the cyclone scale with optional instant transition
`setRotationSpeed`	(speed: number) => void	Set the cyclone rotation speed (0-4)
`isActive`	boolean	Whether the cyclone is animating
`isMoving`	boolean	Whether the cyclone is moving along a path
`progress`	number	Animation progress from 0 to 1
`scale`	number	Current cyclone scale
`rotationSpeed`	number	Current rotation speed

useExplosionControl

Trigger and reset explosion effects. Returns null until the component with the matching ID mounts.

import { useExplosionControl, MapExplosion } from "@/registry/map";

const Explosion = () => {
  const control = useExplosionControl("my-explosion");

  return (
    <>
      <MapExplosion id="my-explosion" coordinates={[-74.006, 40.7128]} />
      <button onClick={control?.trigger}>Trigger Explosion</button>
      <button onClick={control?.reset}>Reset</button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the explosion component to control

Return Value	Type	Description
`trigger`	() => void	Trigger the explosion
`reset`	() => void	Reset the explosion state
`isExploding`	boolean	Whether the explosion is active

useFireControl

Control fire animation and intensity. Returns null until the component with the matching ID mounts.

import { useFireControl, MapFire } from "@/registry/map";

const Fire = () => {
  const control = useFireControl("my-fire");

  return (
    <>
      <MapFire id="my-fire" coordinates={[-122.4194, 37.7749]} />
      <button onClick={control?.isActive ? control.stop : control?.start}>
        {control?.isActive ? "Extinguish" : "Ignite"}
      </button>
      <button onClick={() => control?.setIntensity(0.9)}>
        Max Intensity
      </button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the fire component to control

Return Value	Type	Description
`start`	() => void	Start the fire animation
`stop`	() => void	Stop the fire animation
`setIntensity`	(intensity: number) => void	Set the fire intensity
`isActive`	boolean	Whether the fire is burning
`spreadProgress`	number	Fire spread progress from 0 to 1

useLightningControl

Trigger lightning strike effects. Returns null until the component with the matching ID mounts.

import { useLightningControl, MapLightning } from "@/registry/map";

const Lightning = () => {
  const control = useLightningControl("my-lightning");

  return (
    <>
      <MapLightning id="my-lightning" coordinates={[-87.6298, 41.8781]} />
      <button onClick={control?.strike}>Strike!</button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the lightning component to control

Return Value	Type	Description
`strike`	() => void	Trigger a lightning strike
`isActive`	boolean	Whether a strike is in progress

useMeteorControl

Control meteor animation and track impact phases. Returns null until the component with the matching ID mounts.

import { useMeteorControl, MapMeteor } from "@/registry/map";

const Meteor = () => {
  const control = useMeteorControl("my-meteor");

  return (
    <>
      <MapMeteor id="my-meteor" target={[37.6173, 55.7558]} />
      <button onClick={control?.isActive ? control.stop : control?.start}>
        {control?.isActive ? "Stop" : "Launch"} Meteor
      </button>
      <p>Phase: {control?.phase}</p>
      <p>Progress: {Math.round((control?.progress ?? 0) * 100)}%</p>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the meteor component to control

Return Value	Type	Description
`start`	() => void	Start the meteor animation
`stop`	() => void	Stop the meteor animation
`reset`	() => void	Reset the meteor to initial state
`isActive`	boolean	Whether the meteor is animating
`progress`	number	Animation progress from 0 to 1
`phase`	"falling" \| "impact" \| "fading" \| "idle"	Current meteor phase

useSandstormControl

Control sandstorm animation and intensity. Returns null until the component with the matching ID mounts.

import { useSandstormControl, MapSandstorm } from "@/registry/map";

const Sandstorm = () => {
  const control = useSandstormControl("my-sandstorm");

  return (
    <>
      <MapSandstorm id="my-sandstorm" />
      <button onClick={control?.isActive ? control.stop : control?.start}>
        {control?.isActive ? "Stop" : "Start"} Sandstorm
      </button>
      <button onClick={() => control?.setIntensity(0.7)}>
        Increase Intensity
      </button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the sandstorm component to control

Return Value	Type	Description
`start`	() => void	Start the sandstorm animation
`stop`	() => void	Stop the sandstorm animation
`setIntensity`	(intensity: number) => void	Set the sandstorm intensity
`isActive`	boolean	Whether the sandstorm is active

useSnowControl

Control snow animation and intensity. Returns null until the component with the matching ID mounts.

import { useSnowControl, MapSnow } from "@/registry/map";

const Snow = () => {
  const control = useSnowControl("my-snow");

  return (
    <>
      <MapSnow id="my-snow" />
      <button onClick={control?.isActive ? control.stop : control?.start}>
        {control?.isActive ? "Stop" : "Start"} Snow
      </button>
      <button onClick={() => control?.setIntensity(0.5)}>
        Light Snow
      </button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the snow component to control

Return Value	Type	Description
`start`	() => void	Start the snow animation
`stop`	() => void	Stop the snow animation
`setIntensity`	(intensity: number) => void	Set the snow intensity
`isActive`	boolean	Whether the snow is falling

useSteamControl

Control steam animation and intensity. Returns null until the component with the matching ID mounts.

import { useSteamControl, MapSteam } from "@/registry/map";

const Steam = () => {
  const control = useSteamControl("my-steam");

  return (
    <>
      <MapSteam id="my-steam" coordinates={[-155.2833, 19.4069]} />
      <button onClick={control?.isActive ? control.stop : control?.start}>
        {control?.isActive ? "Stop" : "Start"} Steam
      </button>
      <button onClick={() => control?.setIntensity(0.6)}>
        Medium Steam
      </button>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the steam component to control

Return Value	Type	Description
`start`	() => void	Start the steam animation
`stop`	() => void	Stop the steam animation
`setIntensity`	(intensity: number) => void	Set the steam intensity
`isActive`	boolean	Whether the steam is active

useTsunamiControl

Control tsunami animation and track wave phases. Returns null until the component with the matching ID mounts.

import { useTsunamiControl, MapTsunami } from "@/registry/map";

const Tsunami = () => {
  const control = useTsunamiControl("my-tsunami");

  return (
    <>
      <MapTsunami id="my-tsunami" origin={[142.3728, 38.3215]} target={[141.0, 37.0]} />
      <button onClick={control?.isActive ? control.stop : control?.start}>
        {control?.isActive ? "Stop" : "Start"} Tsunami
      </button>
      <p>Phase: {control?.phase}</p>
      <p>Progress: {Math.round((control?.progress ?? 0) * 100)}%</p>
    </>
  );
};

Parameter	Type	Description
`id`	string	The ID of the tsunami component to control

Return Value	Type	Description
`start`	() => void	Start the tsunami animation
`stop`	() => void	Stop the tsunami animation
`reset`	() => void	Reset the tsunami to initial state
`isActive`	boolean	Whether the tsunami is animating
`progress`	number	Animation progress from 0 to 1
`phase`	"approaching" \| "crashing" \| "receding" \| "idle"	Current tsunami phase

← PreviousComponents Next →Reference