---
title: "capture-coordinates"
description: "Capture the user’s current GPS location and show it on a map."
permalink: /docs/runtime/all-ui-components/capture-coordinates/
---
# capture-coordinates
## Overview
The `capture-coordinates` component allows users to capture their current location. The captured location will be displayed on a map with a marker.
### Light Mode
### Dark Mode
### Basic Examples
#### Capture coordinates & markers
The following example shows how GPS location capturing can show a mix between `marker-query` and `marker` nodes.
In the example the captured location will be bound to the variable specified in the `capture-coordinates` `bind` attribute. Markers are simply locations that are being visually highlighted on a map. This is useful to, for example, show where the captured location is in relation to other points of interest.
```xml
```
#### "Foreground" Capturing
The following example shows how GPS location capturing can be performed in the "foreground" i.e. the user sees a map showing how their GPS location is captured.
```xml
```
#### "Background" Capturing
Using the `show-if` configuration option, it is also possible to capture a GPS location in the background (i.e. the map pictured in the screenshot above is not shown)
```xml
```
## Standard Attributes
### `bind`
The `capture-coordinates` component uses the GPS location of the device and sets this value on the `bind` variable/field. This value will update as accuracy increases of the device's GPS location. A marker will autogenerate at the bound location if no `` or `` is defined. See [show-markers](#show-markers) for more information on hiding markers.
Must be a variable or field of type `location`. See the reference on [data model fields](/docs/data-model/model/field/) for more details.
```xml
```
## Advanced Attributes
### `align-controls`
Specify the alignment of the map’s controls. **Note**: controls are visible when the [`allow-zoom`](#allow-zoom) or [`allow-dragging`](#allow-dragging) attributes are enabled.
**main.view\.xml**
```xml
align-controls="center"
align-controls="left"
align-controls="right"
```
### `allow-dragging`
Allow panning the map through touch gestures or mouse click-and-drag movements.
```xml
```
### `allow-zoom`
Display the zoom controls on the component and allow changing the zoom level of the map with touch gestures or by scrolling.
### capture-coordinates
**main.view\.xml**
```xml
```
### display-coordinates
**main.view\.xml**
```xml
```
### `height`
Specify the height (in pixel) of the `capture-coordinates` / `display-coordinates` component.
### capture-coordinates
**main.view\.xml**
```xml
```
### display-coordinates
**main.view\.xml**
```xml
```
### `on-location`
**Triggered when**: The user selects a location within the map
**Event parameter**: `$value`
**Return value**: Location object containing the latitude and longitude
`on-location` is an event that calls a JS/TS [`$:function`](/docs/get-started/syntax/expressions-and-events/) or [navigation](/docs/runtime/view-navigation/). See more details:
- [Expressions and Events](/docs/get-started/syntax/expressions-and-events/#call-functions-from-events)
**main.view\.xml**
```xml
/>
```
**main.js**
```javascript
function onLocation(location) {
console.log(location);
// Example:
// Object{latitude: 39.7553694, longitude: -105.0195773}
}
```
Set `allow-zoom` and `allow-dragging` to `true` to allow users to navigate to different locations on the map.
### `show-markers`
Show or hide all the markers on the map. `show-if`/`hide-if` on individual markers is also available.
### capture-coordinates
**main.view\.xml**
```xml
```
### display-coordinates
**main.view\.xml**
```xml
```
### `align-content`
### `align-label`
### `label-case`
### `label-color`
### `id`
### `on-change`
### `show-if`
### `hide-if`
## Common Attributes
### `label`
### `required`
## Component Methods
The following component methods are available when an [`id`](/docs/runtime/common-component-attributes/id/) is assigned to the component and `component.captureCoordinates({id:'my-id'})` / `component.displayCoordinates({id:'my-id'})` is called from JS/TS:
### `getMapState`
Programmatically retrieve the current state of the map which will contain the current center and zoom position of the map.
### capture-coordinates
**main.view\.xml**
```xml
```
**main.js**
```javascript
try{
component.captureCoordinates({id: 'my-id'}).getMapState();
}catch (e) {
// handle exception here
}
```
### display-coordinates
**main.view\.xml**
```xml
```
**main.js**
```javascript
try{
component.displayCoordinates({id: 'my-id'}).getMapState();
}catch (e) {
// handle exception here
}
```
### `setMapState`
Programmatically set the center and/or zoom position of the map to a specific value.
### capture-coordinates
**main.view\.xml**
```xml
```
**main.js**
```javascript
try{
component.captureCoordinates({id: 'my-id'}).setMapState({
zoom: 12,
center: new Location({longitude: -33.00, latitude: -10.00})
});
}catch (e) {
// handle exception here
}
```
### display-coordinates
**main.view\.xml**
```xml
```
**main.js**
```javascript
try{
component.displayCoordinates({id: 'my-id'}).setMapState({
zoom: 12,
center: new Location({longitude: -33.00, latitude: -10.00})
});
}catch (e) {
// handle exception here
}
```
### `scrollIntoView`
Programmatically scroll until the `capture-coordinates` component is visible in the view.