Skip to content
NewYour data: charts, lists and meters that take your records
<GeoCoordinate />ReactInputs & timeForm control

Coordinate field

A text field for coordinates in decimal or DMS notation, with a small world map whose parallel and meridian follow what it reads.

View as Markdown
<GeoCoordinate />

Trytype 35°41′22″N 139°41′30″E, then change N to S.

Playground

Change a prop and the component re-renders. Props marked remounts set an initial value, so the component starts over.

Loading <GeoCoordinate />
Props
formatlive
precisionlive
normalizeOnBlurlive
labellive
requiredlive
disabledlive
React
<GeoCoordinate
  format="decimal"
  precision={5}
  normalizeOnBlur
  label="Coordinates"
/>

Installation

pnpm dlx shadcn@latest add @lumesec/geo-coordinate
First 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}.json

Or skip the setup and install by URL:

npx shadcn@latest add https://elements.lumesec.ai/r/geo-coordinate.json

Usage

geo-coordinate-example.tsx
"use client";

import * as React from "react";

import { GeoCoordinate, type LatLon } from "@/components/lumesec/geo-coordinate";

export function Example() {
  const [site, setSite] = React.useState<LatLon | null>({ lat: 48.8566, lon: 2.3522 });
  return <GeoCoordinate name="site" label="Site location" value={site} onValueChange={setSite} />;
}

Behaviour

A text field for coordinates that reads the usual ways of writing them: decimal degrees, degrees with minutes and seconds, hemisphere letters, or a signed pair. A small world map beside it shows what it read.

The map has a parallel and a meridian on separate springs: typing the latitude moves the horizontal line, the longitude moves the vertical one, and when both are read the crossing locks with a ping. Below the field the coordinates appear in the other format, with hemisphere letters that flip over when the sign changes.

API reference

Props

Also accepts every prop of <div> (React.ComponentProps<"div">), spread onto the root element.

valueTypeLatLon | null

The point read from the field (controlled). Use with onValueChange. A new value that differs from what the text reads rewrites the field in format.

defaultValueTypeLatLon | nullDefaultnull

Initial point when uncontrolled; shown in format. A form reset restores it.

onValueChangeType(value: LatLon | null) => void

Called when the text reads as a new point, or with null when it stops reading as one.

formatType"decimal" | "dms"Default"decimal"

Notation of the initial text, and of the text when the field is rewritten on blur or by a controlled value: 48.85660° N, 2.35220° E or 48°51′24″ N, 2°21′08″ E.

precisionTypenumberDefault5

Decimals of decimal degrees, 0 to 8. Degrees, minutes and seconds show whole seconds up to 5, and one decimal of the seconds more for each step above 5.

normalizeOnBlurTypebooleanDefaulttrue

Rewrites readable text in format when the field loses focus. The value keeps its full precision.

labelTypestringDefault"Coordinates"

Visible label of the field.

placeholderTypestringDefault"48.8566, 2.3522"

Placeholder of the empty field. When it reads as a point, the map shows that point as faint dotted lines.

nameTypestring

Prefix of the hidden inputs ${name}-lat and ${name}-lon, which submit the point with a surrounding form.

requiredTypebooleanDefaultfalse

Requires a readable point: an empty field is marked invalid on blur and blocks form submission.

disabledTypebooleanDefaultfalse

Disables the field and the copy button. setText on the handle is ignored too.

refTypeReact.Ref<GeoCoordinateHandle>

Exposes setText(text) and focus(); the root div takes no ref.

Ref

ref receives a GeoCoordinateHandle handle with these methods.

setText(text: string): void

Puts text into the field as if it were typed: the map and the readout follow, and onValueChange fires when the point the text reads changes.

focus(): void

Moves focus to the field.

Keyboard

KeysAction
TabMoves from the field to the copy button, which is in the tab order once the text reads as a point.
Enter / SpaceOn the copy button: copies the coordinates as the readout shows them.

Accessibility

  • The field is a native text input with a visible label. aria-describedby points at the readout below it, or at the error message while the text is invalid.
  • Text that cannot be read sets aria-invalid on blur and shows "Use latitude, longitude, for example 48.8566, 2.3522" in the destructive colour. The same message is the input's custom validity, so a surrounding form does not submit.
  • A polite live region announces the point in the readout's notation once typing pauses for 0.7 seconds, the error message on blur, and "Coordinates copied".
  • The copy button is a native button named "Copy coordinates". It is disabled until the text reads as a point.
  • The map and its canvases are aria-hidden; the readout below the field carries the same information as text.
  • With name, two hidden inputs submit the point: ${name}-lat and ${name}-lon, in decimal degrees at full precision, empty while there is no point. The visible text field has no name. required sets the native required attribute, unreadable text sets a custom validity, and a form reset restores defaultValue.
  • Reduced motion: the lines appear at their positions without springs or afterimages, the bracket appears without snapping in, and there is no ping, spark or border flash. The readout's digits and hemisphere letters change without rolling or flipping, the land does not fade in, and invalid text is marked without the shake.

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-soft, --lumesec-glint, --lumesec-shine, --destructive, --background, --card, --muted, --muted-foreground, --foreground, --border and --input.

Notes

  • The field reads signed decimal pairs separated by a comma, space, semicolon or slash (48.8566, 2.3522, -22.9068 -43.1729), hemisphere letters or words before or after each number (N 48.8566 E 2.3522), degrees, minutes and seconds with ° ′ ″ ' " or d m s (35°41′22″N 139°41′30″E), degrees with decimal minutes (40 42.768 N 74 0.36 W), and decimal commas when they are unambiguous (48,8566; 2,3522). Letters that say longitude came first swap the pair.
  • Half-typed text already moves the map: when only the first part is readable it counts as latitude, or as longitude when it carries E or W. onValueChange reports null until the whole text reads as a point.
  • The readout below the field uses the other notation than the text: degrees, minutes and seconds under decimal text, decimal degrees under DMS text. Its digits roll in the direction of change and each hemisphere letter flips over when the sign changes. The copy button copies the readout as shown.
  • The map is a 112 × 56 px equirectangular view of the whole world with land dots every 2.5 px. Below 340 px of width the map moves under the field and fills the width.
  • The parallel and the meridian each ride a spring (stiffness 300, damping 0.75) and slide in from the map centre when their axis becomes known. A line moving faster than 120 px/s leaves three afterimages. When both lines have settled, the crossing locks: a 9 px bracket snaps in from 1.6 times its size and a ring of light runs through the land dots within 10 px. A lock that follows a change in the text also flashes the field's border and sends a few sparks past the map's edge.
  • An empty field is valid unless required. Invalid text is marked on blur, and the mark clears on the next edit.
  • The root carries data-state: empty, partial (one axis read), complete or invalid, for styling around the field.

Was this page helpful?