Location picker
Choose a point on a dot map by click, search or typed coordinates. The pin drops on a spring and lands with a splash that ripples the dots.
Your data
Pass your own places as places. Without it the search and snapping use 60 demo cities; nothing about the viewer's location is read or inferred, and the picker starts without a pin unless you pass one. See Your data.
Playground
Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.
<GeoLocationPicker
defaultValue={{
lat: 40.7128,
lon: -74.006
}}
snap={25}
maxZoom={4}
precision={4}
label="Location"
/>Installation
pnpm dlx shadcn@latest add @lumesec/geo-location-pickerFirst timeRegister the @lumesec registry once, or install by URL
Adds @lumesec to your components.json:
pnpm dlx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.jsonOr skip the setup and install by URL:
npx shadcn@latest add https://elements.lumesec.ai/r/geo-location-picker.jsonUsage
import { GeoLocationPicker } from "@/components/lumesec/geo-location-picker";
export function Example() {
return (
<form>
<GeoLocationPicker name="site" snap={25} defaultValue={{ lat: 6.5244, lon: 3.3792 }} required />
</form>
);
}Behaviour
Choose a point on a map. Click or tap to drop the pin, search for a place, or type exact coordinates into the latitude and longitude fields.
The pin drops on a bouncy spring and lands with a splash: the dots around it are pushed outward in a ring like water, and the coordinates roll to the new values. Picking a search result flies the map there and zooms in so you can place the pin precisely.
API reference
Props
Also accepts every prop of <div> (React.ComponentProps<"div">), spread onto the root element.
valueTypeLatLon | nullPin position (controlled). Use with onValueChange. null shows no pin.
defaultValueTypeLatLon | nullDefaultnullPin position when uncontrolled. A form reset restores it.
onValueChangeType(value: LatLon | null) => voidCalled when the pin moves or is cleared.
placesTypereadonly PickerPlace[]Default60 demo cities{ id, label, lat, lon } for the search and for snapping. Without it the 60 demo cities of DEMO_CITIES are used. An empty array leaves the search with coordinates only.
snapTypenumber | falseDefaultfalseSnaps a pin dropped on the map (click, tap or Enter) to the nearest place within this many km. Arrow keys and the coordinate fields set exact values.
maxZoomTypenumberDefault4Largest map zoom, from 1 to 6.
precisionTypenumberDefault4Decimals of the latitude and longitude, from 0 to 6. Dropped, stepped and typed values are rounded to it; snapped values keep the place's coordinates.
nameTypestringForm field name. With a name and a pin, hidden inputs submit the coordinates.
submitAsType"fields" | "pair"Default"fields"fields submits name-lat and name-lon; pair submits one name field with 'lat,lon'.
requiredTypebooleanDefaultfalseBlocks form submission while there is no pin.
disabledTypebooleanDefaultfalseDims the picker, ignores the pointer and the keyboard, and submits nothing.
labelTypestringDefault"Location"Accessible name of the group.
Ref
ref points at the root HTMLDivElement.
Keyboard
| Keys | Action |
|---|---|
| ArrowDown / ArrowUp (search) | Moves through the results; opens them again when closed. |
| Enter (search) | Picks the highlighted result: the map flies there and the pin drops on it. |
| Escape (search) | Closes the results, or clears the text when they are closed. |
| Arrow keys (map) | Move the pin 1°, or 5° with Shift, with a small drop. Without a pin they pan the zoomed map. |
| + / − (map) | Zoom in or out one step about the view centre. |
| Enter / Space (map) | Drops a pin at the view centre when there is none. |
| Delete / Backspace (map) | Removes the pin. |
| ArrowUp / ArrowDown (fields) | Change the coordinate by 0.1°, or 1° with Shift. |
| PageUp / PageDown (fields) | Change the coordinate by 10°. |
| Home / End (fields) | Set the coordinate to its limit: −90 and 90 for the latitude, −180 and 180 for the longitude. |
| Enter (fields) | Commits typed text. On unchanged text it submits the form, like a native field. |
| Escape (fields) | Reverts typed text. |
Accessibility
- The root is a
role="group"named bylabel. - The search is a
role="combobox"witharia-expanded,aria-controlsandaria-activedescendant; the results are arole="listbox"of options. - The map is focusable, with
role="application",aria-roledescription="map"and the label 'Map: arrow keys move the pin, plus and minus zoom'. The line under the map describes it. Its canvases and the pin arearia-hidden. - Latitude and Longitude are text inputs with
role="spinbutton",aria-valuemin,aria-valuemax,aria-valuenowand anaria-valuetextsuch as '6.5244° N'. - Pin moves are announced politely, such as 'Pin at 6.52° N, 3.38° E'.
- The zoom buttons have accessible names: Zoom out, Zoom in, Reset view.
- With
nameand a pin, hidden inputs submitname-latandname-lon(ornamewith 'lat,lon' forsubmitAs="pair") atprecisiondecimals. Nothing is submitted without a pin or while disabled.requiredblocks submission without a pin through a hidden input whose custom validity message is 'Drop a pin on the map.'; the map card turns red and shakes until a pin is dropped. A form reset restoresdefaultValueand the whole-world view. - Reduced motion: the pin is placed without the drop, squash or splash (the lit pool under it stays), search picks jump the view without the flight, zoom and pan jump, the new land fades in at once, and the coordinates swap without rolling.
Theming
Styled with Tailwind classes on your shadcn theme tokens, so light and dark follow your theme. The accent comes from --lumesec. See Theming.
This component reads --lumesec, --lumesec-glint, --card, --popover, --popover-foreground, --muted, --muted-foreground, --foreground, --border and --destructive.
Notes
- The map is an equirectangular strip from 60° S to 78° N, drawn as land dots from the embedded world data with no map tiles. A latitude outside the strip is valid; its pin sits on the nearest edge. A
valuewith a latitude beyond ±90° or a coordinate that is not finite shows no pin; a longitude beyond ±180° is wrapped. - Zoom and centre are springs. A search pick flies the map to the place on one spring and zooms in to at least 3× (or
maxZoom); long flights dip out halfway. The pin waits until the flight is almost there, then drops. - The land is re-baked at a 4 px pitch for each resting zoom and fades in over 160 ms; while the view moves, the last bake is drawn scaled, so dots spread apart on the way in. A press that moves less than 4 px drops the pin; a drag pans the map when it is zoomed. At 1× a vertical touch swipe scrolls the page.
- The drop is an under-damped spring drawn as one rebound off the ground. At first contact the pin squashes, the dots within 40 px are pushed outward on an uneven ring and brighten toward the glint, a weaker ring pulls them back, and a small lit pool stays under the pin.
- The coordinate fields show rolling figures while they do not have focus. Typed text accepts a sign or a hemisphere letter ('33.87 S'); invalid text shakes the field and reverts. Without a pin, field input starts from the view centre.
- The line under the map shows the place the pin is on ('Lagos', or 'Lagos, 3.4 km away' after a snap), else the pin in degrees, minutes and seconds. The figure on the right is the zoom.
Related
Was this page helpful?