Location Field

The Location Field component provides an input for geographic coordinates, storing latitude and longitude as a structured object.

Basic Usage

With Default Value

Read-Only

Field Schema

A location field is authored as LocationFieldMetadata (@object-ui/types), which is the source of truth for the key set: it extends BaseFieldMetadata with the map's default zoom level.

import type { LocationFieldMetadata } from '@object-ui/types';

const officeLocation: LocationFieldMetadata = {
  type: 'location',
  name: 'office_location',
  label: 'Office Location',
  placeholder: 'latitude, longitude',
  required: false,
  default_zoom: 12,
};

The coordinates themselves are the field's value, not metadata: the widget stores an object carrying a lat and an lng and displays it as a comma-separated pair. That value shape is exported as LocationValue by @objectstack/spec/data — { lat, lng, altitude?, accuracy? } — and it is what valueSchemaFor({ type: 'location' }) validates a stored location against.

The value being edited, and the className / disabled a host supplies, are not metadata keys — they are runtime widget props. See Field Widget Props.

Data Format

The location field stores coordinates as an object:

{
  lat: 37.7749,
  lng: -122.4194
}

altitude and accuracy are optional numbers on the same object.

Note: the stored keys are lat and lng. The older { latitude, longitude } spelling is deprecated and is rejected by valueSchemaFor({ type: 'location' }) with invalid_type at [lat] and [lng] — do not author it.

Input format: latitude, longitude — a user still types a comma-separated latitude-then-longitude pair; only the stored key names are lat / lng.

• Example: 37.7749, -122.4194

Coordinate Ranges

• Latitude (lat): -90 to 90 (negative = South, positive = North)
• Longitude (lng): -180 to 180 (negative = West, positive = East)

Examples:

• New York: 40.7128, -74.0060
• Tokyo: 35.6762, 139.6503
• Sydney: -33.8688, 151.2093
• London: 51.5074, -0.1278

Use Cases

• Store Locator: Retail locations, branch offices
• Delivery Zones: Service areas, delivery points
• Event Venues: Conference locations, meeting points
• Asset Tracking: Equipment locations, vehicle tracking
• Real Estate: Property coordinates, land parcels

Integration with Maps

For full map functionality, consider integrating with map services. The example below has two halves: the input that captures a coordinate pair, and the map node that plots what it stored.

1. The input. LocationField is the widget behind the location field type. Render it directly when you build the form yourself:

import { useState } from 'react';
import { LocationField } from '@object-ui/fields';
import type { LocationFieldMetadata } from '@object-ui/types';

const field: LocationFieldMetadata = {
  type: 'location',
  name: 'location',
  label: 'Store location',
};

export function StoreLocationInput() {
  const [value, setValue] = useState<{ lat: number; lng: number } | null>(null);
  return <LocationField field={field} value={value} onChange={setValue} />;
}

2. The map over the same field. With the map plugin installed, an object-map node reads that field off every record. It is a metadata node, not a component call — the keys sit on the node itself, and a props envelope is never read by the renderer:

{
  "type": "object-map",          // the registered type name — there is no `plugin:map`
  "objectName": "store",         // the records to plot
  "map": {                       // the declared config input; markers are derived from the data
    "locationField": "location", // this page's field, read as { lat, lng }
    "titleField": "name",        // field used as the marker label
    "zoom": 12,                  // initial zoom level
    // Initial centre as [latitude, longitude]. Used only when no record
    // matches — with records the view fits to their bounds instead.
    "center": [37.7749, -122.4194]
  }
}

Note: the map plots the records it fetches, so it takes an objectName (or an explicit data array) rather than a bind path, and it derives its markers from those records — a markers key on the node is not read. Every marker setting lives under the declared map input.

Validation

The field validates coordinate ranges:

// Valid coordinates
{ lat: 37.7749, lng: -122.4194 } ✓

// Invalid - latitude out of range
{ lat: 95, lng: -122.4194 } ✗

// Invalid - longitude out of range
{ lat: 37.7749, lng: 200 } ✗