Skip to content
NewYour data: charts, lists and meters that take your records
<GeoIp />ReactAccess & securityForm control

IP lookup

A field that looks up where an IP address is located and shows the result on a small map.

View as Markdown
<GeoIp />

Trylook up 198.51.100.7, then 192.168.1.20.

Your data

Pass your lookup as resolve. Without it the component invents a location for every public address from a hash of the address, which is only useful for demos. See Your data.

Playground

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

Loading <GeoIp />
Props
defaultValueremounts
formatlive
autoResolvelive
disabledlive
React
<GeoIp defaultValue="203.0.113.42" format="decimal" autoResolve />

Installation

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

Usage

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

import { GeoIp, type GeoIpResult } from "@/components/lumesec/geo-ip";

async function resolve(address: string): Promise<GeoIpResult | null> {
  const response = await fetch(`/api/ip/${encodeURIComponent(address)}`);
  if (!response.ok) return null;
  const result: GeoIpResult = await response.json();
  return result;
}

export function Example() {
  return <GeoIp defaultValue="203.0.113.42" resolve={resolve} />;
}

Behaviour

A field that looks up where an IP address is located and shows the result on a small map. While the lookup runs, a crosshair hops from land dot to land dot and slows down like a slot machine before it locks onto the result.

The coordinates roll into place, and the place, network and accuracy appear below. Private and reserved addresses are answered at once without a lookup. Bring your own resolve function; the built-in one invents a location and is only for demos.

API reference

Props

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

valueTypestring

Address in the field (controlled). Use with onValueChange.

defaultValueTypestringDefault"203.0.113.42"

Initial address when uncontrolled.

onValueChangeType(value: string) => void

Called as the field changes, and when lookup(address) on the handle puts a new address into it.

resolveType(address: string) => Promise<GeoIpResult | null>Defaultdemo resolver

Looks up a normalised address (203.0.113.42, 2001:db8::1) and resolves with { lat, lon, city?, region?, country?, network?, accuracyKm? }, or null when the address is unknown. A rejected promise counts as unknown. Answers often come straight from JSON, so each field is checked: lat and lon must be numbers or numeric strings, text fields must be strings, and anything else is left out. The default invents a location and is for demos only.

onResultType(address: string, result: GeoIpResult | null) => void

Called once per lookup with the normalised address and the answer: the location, or null for an unknown, private or reserved address. Answers to a lookup that a newer one replaced are dropped.

autoResolveTypebooleanDefaulttrue

Looks up the initial address the first time the map scrolls into view.

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

Coordinate notation of the result: decimal degrees (50.11° N) or degrees, minutes and seconds (50°06′40″ N).

labelTypestringDefault"IP address"

Visible label of the field.

nameTypestring

Name of the input, so the typed address submits with a surrounding form.

placeholderTypestringDefault"Enter an IP address"

Placeholder of the empty field.

disabledTypebooleanDefaultfalse

Disables the field and the button. Lookups through the handle are ignored too.

Ref

ref receives a GeoIpHandle handle with these methods.

lookup(address?: string): void

Runs a lookup, like pressing Enter in the field. With address, the field first changes to it and onValueChange fires; without it, the address in the field is looked up.

focus(): void

Moves focus to the field.

Keyboard

KeysAction
EnterIn the field: looks up the address. It does not submit a surrounding form.
TabMoves from the field to the Look up button.
Enter / SpaceOn the Look up button: looks up the address in the field.

Accessibility

  • The field is a native text input with a visible label. The hint next to the label ("IPv4 or IPv6") describes it through aria-describedby.
  • An invalid address sets aria-invalid on the field, and the hint changes to "Not a valid IP address" in the destructive colour.
  • The Look up button has aria-busy while a lookup runs.
  • A polite live region announces each answer once, such as "Approximately Singapore, 1.29° N, 103.85° E", "No location found for this address" or "Private or reserved address, no location".
  • The map and its canvases are aria-hidden; the place, coordinates, network and accuracy below it are text.
  • A native text input. With name the typed address submits with a surrounding form. Enter in the field runs a lookup instead of submitting the form, and the Look up button is type="button".
  • Reduced motion: there is no hunt, ping or sparks: the crosshair appears on the result when the answer arrives, the accuracy ring is drawn at once, and the land does not fade in. The text below the map changes without rolling, and an invalid address 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

  • Addresses are IPv4 dotted quads or IPv6 addresses, compressed, with an IPv4 tail or in brackets. The address passed to resolve and onResult is normalised: 2001:0db8:0:0::1 becomes 2001:db8::1.
  • Private, shared, loopback, link-local, multicast, unspecified and reserved addresses are answered at once without calling resolve: the map dims and the network row names the range. The documentation ranges (192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24, 2001:db8::/32 and 3fff::/20) count as public addresses, so examples can use them.
  • While resolve runs, the crosshair hops between random land dots; hop n waits min(260, 40 × 1.22^n) ms. When the answer arrives, three to five hops close in on it, each within half the remaining distance, and the last one springs onto the exact point. An answer that arrives within 300 ms still plays these hops. The hops are seeded by the address, so the same address always hunts the same way.
  • onResult fires when the answer arrives; the place and coordinates appear once the crosshair locks, a moment later. When the map is off screen, the result locks at once.
  • The map is equirectangular, cropped to 58° S to 84° N, with land dots every 3.5 px. A point outside that band sits on the nearest edge. The dotted ring shows accuracyKm at its true size on the map, with a radius of at least 4 px.
  • The default resolve maps a hash of the address to one of 60 demo cities, moves the point 5 to 40 km away, reports 20 to 80 km accuracy and a documentation AS number (64496 to 64511), and answers after 0.7 to 1.4 seconds. It never contacts a service.

Was this page helpful?