LocationField

<caos-location-field>

enter a place as one latitude and longitude pair that commits together and is refused the way a save refuses it

May be placed on a record page, a page inside an app and a step of a guided flow.

Inputs

Name	Attribute	Description	Type	Default	Required
label	label, markup only	The field’s name, drawn above the two boxes and naming the group they form. Left unset, no label is drawn.	text	none declared	Optional
latitude	latitude, markup only	The latitude of the place already set, shown in the first box. Written back here whenever a pair is committed, and removed when the place is cleared.	number	none declared	Optional
longitude	longitude, markup only	The longitude of the place already set, shown in the second box. Written back here whenever a pair is committed, and removed when the place is cleared.	number	none declared	Optional
required	required, markup only	This field has to be filled in. Draws the asterisk and marks both boxes required. Leaving it empty is answered by the save, as it is for every other field.	boolean	false	Optional
disabled	disabled, markup only	You may not type in this. Greys both boxes and refuses focus.	boolean	false	Optional
readonly	readonly, markup only	You may read this, select it and copy it, but not change it. Unlike disabled, both boxes stay in full colour and can be focused; nothing typed or pasted is committed.	boolean	false	Optional
invalid	invalid, markup only	The place as a whole is wrong. Turns both boxes and the field message red. For a reason that belongs to one coordinate, use that coordinate’s message instead.	boolean	false	Optional
message	message, markup only	The line under both boxes — muted helper text on its own, the red reason when invalid is also set.	text	none declared	Optional
latitudeMessage	latitude-message, markup only	A reason the page has for refusing the latitude, shown in red under that box. A reason the control finds itself is shown ahead of it.	text	none declared	Optional
longitudeMessage	longitude-message, markup only	A reason the page has for refusing the longitude, shown in red under that box. A reason the control finds itself is shown ahead of it.	text	none declared	Optional
inline	inline, markup only	Draw the record-detail variant: two underlined boxes in the surrounding type, each with its Latitude or Longitude label beside it. The group label and the field message are hidden; the box labels and a refusal under a box are not.	boolean	false	Optional

Events

Name	When it fires	What it carries
change	A different pair, or no place, is committed — focus leaves the whole control, or Enter is pressed. Never when focus moves between the two boxes, never for a pair that is refused, and never for the pair already committed.	nothing; read value for the pair

Slots

Nothing goes inside this piece.

Styling hooks

Design token	What it controls
--caos-font	The typeface of the labels, the boxes and the messages.
--caos-text-body	The size of the group label and of the typed coordinates.
--caos-text-label	The size of the Latitude and Longitude labels.
--caos-space-1	The gap between a label, its box and its message.
--caos-space-3	The gap between the two boxes, and the vertical padding inside each.
--caos-radius	The corner radius of the boxes.
--caos-color-border	The box outline at rest.
--caos-color-border-strong	The box outline while it has focus.
--caos-color-surface-2	The fill of the boxes.
--caos-color-text	The colour of the typed coordinates.
--caos-color-text-muted	The labels, the placeholder, the helper message and disabled text.
--caos-color-accent	The hover outline, and the underline of the inline variant.
--caos-accent-wash	The tint that fills a box while it has focus, in place of a focus ring.
--caos-color-danger	The required asterisk, a refused box, and every refusal message.

Methods

Name	Description	Arguments
focus()	Put the caret in the latitude box, with what is there selected.	options: FocusOptions

Readable state

Name	Type	What it tells you
value	{ latitude: number; longitude: number }	null
holdsRefusal	boolean	Whether a refusal the control found is showing under either box, so the pair is held rather than committed. A host that closes the control when focus leaves reads this to keep it open instead of dropping what was typed.

Styling parts

Part	Which piece of it	When it is there
::part(label)	the group label above both boxes	Always
::part(control)	the row holding the two boxes	Always
::part(latitude)	the latitude box	Always
::part(longitude)	the longitude box	Always
::part(latitude-message)	the refusal under the latitude box	Always
::part(longitude-message)	the refusal under the longitude box	Always
::part(message)	the line under both boxes	Always

When to use it

A place the person types or pastes as coordinates, where the value is a Geolocation field or will be saved as one. Reach for it over two NumberFields whenever the two numbers are one place: that is what makes them commit together, and what keeps an empty box from being saved as zero.

What to use instead

• FieldRenderer — The type is not known until the record is read — hand it the field metadata and it draws this piece for a Geolocation field.
• NumberField — The number stands on its own — an elevation, a radius, a distance.
• TextField — The place is an address a person reads, not a point on a map.

Accessibility

The two boxes sit in a group named by the label, and each is a real text input with its own label, so each is announced as “Latitude” or “Longitude” within the field. They open the decimal keypad on a touch device. A refusal is tied to its box with aria-describedby and marks that box aria-invalid, so it is read with the box it is about. The box labels stay on screen in the inline variant as well: a record page opens it already holding a place, where a placeholder would never be seen.

Examples

A place already set

A site with its coordinates filled in — the two numbers that are one place, side by side under one label.

{
  "id": "example",
  "section": "A place already set",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site",
        "latitude": 29.7604,
        "longitude": -95.3698
      }
    }
  ]
}

<caos-location-field label="Site" latitude="29.7604" longitude="-95.3698"></caos-location-field>

A coordinate refused

The same field holding a latitude that is not on Earth: the refusal sits under the latitude box alone, and the longitude that is fine stays unmarked.

{
  "id": "example",
  "section": "A coordinate refused",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site",
        "latitude": 129.7604,
        "longitude": -95.3698,
        "latitude_message": "Latitude 129.7604 is outside the range -90 to 90, so it is not a point on Earth."
      }
    }
  ]
}

<caos-location-field label="Site" latitude="129.7604" longitude="-95.3698" latitude-message="Latitude 129.7604 is outside the range -90 to 90, so it is not a point on Earth."></caos-location-field>

Required and empty

An empty field that has to be filled in — the asterisk on the group label, and both boxes marked required.

{
  "id": "example",
  "section": "Required and empty",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site",
        "required": true
      }
    }
  ]
}

<caos-location-field label="Site" required></caos-location-field>

Empty, ready for a place

The field with nothing set yet: a Latitude box and a Longitude box under one label, both empty, which means no place.

{
  "id": "example",
  "section": "Empty, ready for a place",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site"
      }
    }
  ]
}

<caos-location-field label="Site"></caos-location-field>

Disabled

A place that may not be changed here at all: both boxes greyed, and neither takes focus.

{
  "id": "example",
  "section": "Disabled",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site",
        "latitude": 29.7604,
        "longitude": -95.3698,
        "disabled": true
      }
    }
  ]
}

<caos-location-field label="Site" latitude="29.7604" longitude="-95.3698" disabled></caos-location-field>

Read-only

A place a person may read and copy but not change. The boxes keep their colour and take focus, so the numbers can be selected — only a dashed edge says they take no typing.

{
  "id": "example",
  "section": "Read-only",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site",
        "latitude": 29.7604,
        "longitude": -95.3698,
        "readonly": true
      }
    }
  ]
}

<caos-location-field label="Site" latitude="29.7604" longitude="-95.3698" readonly></caos-location-field>

With help text

A line under both boxes saying what the place is for, and that a pasted “latitude, longitude” fills the two at once.

{
  "id": "example",
  "section": "With help text",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site",
        "message": "Where the crew reports on day one. Paste \"latitude, longitude\" from any map to fill both boxes."
      }
    }
  ]
}

<caos-location-field label="Site" message="Where the crew reports on day one. Paste &quot;latitude, longitude&quot; from any map to fill both boxes."></caos-location-field>

Right to left

The same field in a right-to-left page. The boxes swap sides with the writing direction; latitude is still the first box in reading order, so it is the one on the right.

The page around it: sets dir="rtl" on the field, as a right-to-left page would on its root.

{
  "id": "example",
  "section": "Right to left",
  "columns": 1,
  "items": [
    {
      "id": "location_field_1",
      "type": "component",
      "key": "location_field",
      "inputs": {
        "label": "Site",
        "latitude": 29.7604,
        "longitude": -95.3698
      }
    }
  ]
}

<caos-location-field label="Site" latitude="29.7604" longitude="-95.3698"></caos-location-field>