IP lookup
A field that looks up where an IP address is located and shows the result on a small map.
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.
<GeoIp defaultValue="203.0.113.42" format="decimal" autoResolve />
Installation
pnpm dlx shadcn@latest add @lumesec/geo-ipFirst 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-ip.jsonUsage
"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.
valueTypestringAddress in the field (controlled). Use with onValueChange.
defaultValueTypestringDefault"203.0.113.42"Initial address when uncontrolled.
onValueChangeType(value: string) => voidCalled as the field changes, and when lookup(address) on the handle puts a new address into it.
resolveType(address: string) => Promise<GeoIpResult | null>Defaultdemo resolverLooks 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) => voidCalled 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.
autoResolveTypebooleanDefaulttrueLooks 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.
nameTypestringName of the input, so the typed address submits with a surrounding form.
placeholderTypestringDefault"Enter an IP address"Placeholder of the empty field.
disabledTypebooleanDefaultfalseDisables the field and the button. Lookups through the handle are ignored too.
Ref
ref receives a GeoIpHandle handle with these methods.
lookup(address?: string): voidRuns 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(): voidMoves focus to the field.
Keyboard
| Keys | Action |
|---|---|
| Enter | In the field: looks up the address. It does not submit a surrounding form. |
| Tab | Moves from the field to the Look up button. |
| Enter / Space | On 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-invalidon the field, and the hint changes to "Not a valid IP address" in the destructive colour. - The Look up button has
aria-busywhile 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
namethe typed address submits with a surrounding form. Enter in the field runs a lookup instead of submitting the form, and the Look up button istype="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
resolveandonResultis normalised:2001:0db8:0:0::1becomes2001: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
resolveruns, 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. onResultfires 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
accuracyKmat its true size on the map, with a radius of at least 4 px. - The default
resolvemaps 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.
Related
Was this page helpful?