@forwardslashns/fws-geo-location-react

React location component that combines:

• Google Places autocomplete for street input.
• FWS GeoNames-backed country/region/city/postal lookup.
• Controlled cascading reset behavior for reliable address forms.
• Themeable UI with responsive layout.

Installation

pnpm add @forwardslashns/fws-geo-location-react

or

npm install @forwardslashns/fws-geo-location-react

Peer dependencies:

• react >= 18
• react-dom >= 18

CSS import

Import styles once in your app entry (recommended):

import "@forwardslashns/fws-geo-location-react/dist/index.css";

Basic usage

import { useState } from "react";
import {
  GeoLocationField,
  type GeoLocationValue,
} from "@forwardslashns/fws-geo-location-react";

export function AddressForm() {
  const [value, setValue] = useState<GeoLocationValue>({});

  return (
    <GeoLocationField
      googleApiKey={import.meta.env.VITE_GOOGLE_MAPS_API_KEY}
      usernames={["your_geonames_username"]}
      value={value}
      onChange={setValue}
    />
  );
}

Required external setup

Google

• Use a valid Google Maps JavaScript API key.
• Enable Maps JavaScript API and Places.
• Enable billing on the Google project.

GeoNames

• Provide at least one username via usernames.
• Multiple usernames are supported and rotated by the API client.

Props

interface GeoLocationFieldProps {
  googleApiKey: string;
  usernames: [string, ...string[]];
  defaultCountryCode?: string; // default: "US"
  value?: GeoLocationValue;
  onChange?: (value: GeoLocationValue) => void;
  fields?: GeoLocationFieldName[];
  theme?: GeoLocationTheme;
  restrictions?: GeoLocationRestrictions;
  className?: string;
}

GeoLocationValue shape:

interface GeoLocationValue {
  street?: string;
  country?: string;
  countryName?: string;
  region?: string;
  regionName?: string;
  city?: string;
  postalCode?: string;
  lat?: number;
  lng?: number;
}

Field rendering and defaults

• Default visible fields: street, country, region, city, postalCode.
• Effective country is value.country when set, otherwise defaultCountryCode, otherwise US.
• Render order is fixed: country -> street -> region -> city -> postalCode.
• Country appears above street in layout.

Behavior contract (important for consumers)

Controlled updates

The component is designed for controlled state. Keep the whole value object in parent state and always use onChange output as the next source of truth.

Cascading reset rules

• Country selection clears street, region, regionName, city, postalCode, lat, lng.
• Street typing clears region, regionName, city, postalCode, lat, lng.
• Region typing/selection clears street, city, postalCode, lat, lng.
• City typing clears postalCode, lat, lng.

This is intentional to prevent stale downstream data after upstream edits.

Street autocomplete reliability

• Street uses react-google-autocomplete with country restriction.
• Selection is parsed and geocode-enriched to fill city/region/postal/coordinates when available.
• Extra postal probes run when initial place payload misses postalCode.
• Race guards prevent stale async writes on fast edits or country switches.
• Immediate post-selection input echo events are ignored to avoid wiping populated values.

Region, city, and postal consistency

• Region/city/postal subcomponents are remounted on country changes for hard state reset.
• Region list requests use filterByPostalCodeAvailability=true.
• City and postal local editing state resets on external context changes.
• Postal lookup supports context narrowing and paginated loading.
• Postal country switch clears in-memory cache and invalidates pending requests.

No results UX

• Region/city/postal do not show No results when a populated input is only focused.
• No results appears only while actively typing and there are no matches.

Theme

You can pass a theme object to override component tokens.

<GeoLocationField
  googleApiKey={googleApiKey}
  usernames={["demo"]}
  value={value}
  onChange={setValue}
  theme={{
    accentColor: "#0f766e",
    labelColor: "#475569",
    containerBorderRadius: "1rem",
    fieldBorderRadius: "0.65rem",
    fontFamily: "Manrope, ui-sans-serif, system-ui, sans-serif",
  }}
/>

The Google suggestion popup is also visually synced to component theme tokens.

Restrictions

restrictions is forwarded to GeoLocationClient, so you can narrow available geography by country/continent according to API capabilities.

Local development

Build:

pnpm build

Watch mode:

pnpm dev

For local playground integration, use link mode so updates are reflected quickly:

{
  "dependencies": {
    "@forwardslashns/fws-geo-location-react": "link:../fws-geo-location-react"
  }
}

Troubleshooting

• Empty street suggestions:
  • verify Google key, billing, and Places enablement.
• No country/region/city/postal data:
  • verify GeoNames usernames are valid and not rate-limited.
• Unexpected value clears:
  • check cascading reset rules above; clears are intentional for data correctness.

License

ISC