AddressField

AddressField renders a Google Maps location picker alongside a set of cascading autocomplete dropdowns (country, subdivision, city, neighborhood) and plain text inputs for street, number, floor, apartment, postal code, and notes. When the user drags the map marker or searches an address, the component reverse-geocodes the position and populates the text fields automatically.

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | label | string | No | — | Field label rendered above the component. | | description | string | No | — | Helper text rendered below the component. | | value | AddressValue | Yes | — | The current address object (see AddressValue shape below). | | onChange | (value: AddressValue) => void | Yes | — | Called with the updated address object on any change. | | countrySearchPath | string | Yes | — | API path used to search countries (e.g. /v1/countries). | | subdivisionSearchPath | string | Yes | — | API path used to search subdivisions / states. | | citySearchPath | string | Yes | — | API path used to search cities. | | neighborhoodSearchPath | string | Yes | — | API path used to search neighborhoods. | | apiBaseUrl | string | No | urls.apiBase | Base URL for all autocomplete API calls. | | useAuthToken | boolean | No | true | Whether to attach the auth token to autocomplete requests. | | searchParam | string | No | 'search' | Query-string parameter name used for the autocomplete search term. | | itemLabelKey | string | No | 'name' | Key inside each autocomplete result object to use as the display label. | | itemIdKey | string | No | 'id' | Key inside each autocomplete result object to use as the identifier. | | apiKey | string | No | keys.googleMaps | Google Maps JavaScript API key. | | width | number \| string | No | '100%' | Width of the map container. | | mapHeight | number \| string | No | 300 | Height of the map in pixels. | | zoom | number | No | 14 | Initial zoom level for the map. | | initialCenter | { lat: number; lng: number } | No | — | Override the initial map center. Defaults to the coordinates in value. | | markerIdleSrc | string | No | '/assets/markers/idle.svg' | URL for the idle map marker image. | | markerDraggingSrc | string | No | '/assets/markers/drag.svg' | URL for the dragging map marker image. | | inputPlaceholder | string | No | 'Buscar dirección...' | Placeholder for the map search input. | | language | string | No | — | Language code for the Google Maps locale. | | region | string | No | — | Region bias for Google Maps geocoding. | | geocodeOnDragEnd | boolean | No | true | Whether to reverse-geocode when the marker is dragged. | | extraInputs | ('block' \| 'lot' \| 'meter_number')[] | No | [] | Additional optional inputs to render (block/lot/meter number). | | containerStyle | React.CSSProperties | No | — | Styles applied to the outer FieldContainer. | | headerStyle | React.CSSProperties | No | — | Styles applied to the field header area. | | bodyStyle | React.CSSProperties | No | — | Styles applied to the field body area. | | labelStyle | React.CSSProperties | No | — | Styles applied to the label element. | | descriptionStyle | React.CSSProperties | No | — | Styles applied to the description paragraph. | | className | string | No | — | CSS class name applied to the outer container. |

AddressValue shape

interface AddressValue {
  name?: string;
  street: string;
  number?: string;
  floor?: string;
  apartment?: string;
  block?: string;
  lot?: string;
  meter_number?: string;
  zone_id?: number | null;
  neighborhood_id?: number | null;
  city_id?: number | null;
  subdivision_id?: number | null;
  country_id?: number | null;
  neighborhood_name?: string;
  city_name?: string;
  subdivision_name?: string;
  country_name?: string;
  formatted_address?: string;
  latitude?: number | null;
  longitude?: number | null;
  postal_code?: string;
  notes?: string;
  country?: any | null;
  subdivision?: any | null;
  city?: any | null;
  neighborhood?: any | null;
}

Usage

Basic

import React, { useState } from 'react';
import AddressField from '@/components/fields/AddressField';

export default function Example() {
  const [address, setAddress] = useState({
    street: '',
  });

  return (
    <AddressField
      label="Delivery Address"
      value={address}
      onChange={setAddress}
      countrySearchPath="/v1/countries"
      subdivisionSearchPath="/v1/subdivisions"
      citySearchPath="/v1/cities"
      neighborhoodSearchPath="/v1/neighborhoods"
    />
  );
}

With extra inputs and custom map height

<AddressField
  label="Property Address"
  value={address}
  onChange={setAddress}
  countrySearchPath="/v1/countries"
  subdivisionSearchPath="/v1/subdivisions"
  citySearchPath="/v1/cities"
  neighborhoodSearchPath="/v1/neighborhoods"
  mapHeight={400}
  zoom={16}
  extraInputs={['block', 'lot']}
/>