gistda-sphere-react

useUi

Built-in controls, mouse and keyboard input, the right-click menu, geolocation and a scroll-friendly map lock

useUi manages Sphere's built-in UI and how users can interact with the map. It works inside SphereMap and anywhere else under SphereProvider.

Right-click the map to open its menu.

import { useUi } from "gistda-sphere-react";

function InputSettings() {
  const ui = useUi();
  return (
    <>
      <button onClick={() => ui.setMouseEnabled({ wheel: false })}>Disable wheel zoom</button>
      <button onClick={() => ui.setKeyboardEnabled(false)}>Disable keyboard</button>
      <button onClick={() => ui.locateUser()}>Where am I?</button>
    </>
  );
}

Return value

MethodDescription
setControlVisible(name, visible) / isControlVisible(name)Show or hide a built-in control.
setMouseEnabled(enabled)true/false for all mouse input, or { click, drag, wheel } to set them one by one.
getMouseState(){ click, drag, wheel }.
setKeyboardEnabled(enabled) / isKeyboardEnabled()Keyboard navigation.
setContextMenuOptions({ address, nearPoi }) / getContextMenuOptions()Show the address and nearby-places entries in the right-click menu.
locateUser()Ask for the user's location and show it on the map.
clearUserLocation()Hide the location marker.
lockMap(config?)Cover the map with a lock until the user clicks it. Returns a MapLockController.
addControl(control) / removeControl(control)Add a MapLibre control or a sphere.CustomControl. For React content, use MapControl.
setLanguage(language)Language of the built-in UI only. To change labels too, use SphereMap's language prop.
isReadytrue once the map is ready.

Lock the map

A map that fills the screen width can trap scrolling: users scroll the page and pan the map instead. lockMap covers the map with a button until the user clicks it:

import { SphereMap, useUi } from "gistda-sphere-react";
import { useEffect } from "react";

function LockedMap() {
  const ui = useUi();

  useEffect(() => {
    if (!ui.isReady) return;
    const lock = ui.lockMap({ unlockLabel: "Click to use the map" });
    return () => lock?.remove();
  }, [ui]);

  return null;
}

<SphereMap style={{ height: 400 }}>
  <LockedMap />
</SphereMap>
config optionDescription
unlockLabel / lockLabelButton text while locked / unlocked. Defaults depend on the map language.
unlockClassName / lockClassNameButton classes. Without them, a small default style is added.
MapLockControllerDescription
isLocked()Whether the map is locked.
lock() / unlock()Lock or unlock from code.
remove()Remove the lock entirely.

Calling lockMap again on the same map returns the existing lock instead of stacking a second one.

Disabling all input

To make a static map, turn interaction off when creating it:

import { SphereMap } from "gistda-sphere-react";

<SphereMap input={false} controls={{ DPad: false, Zoombar: false }} />

On this page