Map Controls

UI components that provide user interactivity and control features for the map. All built-in controls must adhere to the Control Interface.

1. Control (Interface)

The base interface for any UI element that can be added to the map using map.addControl().

This is an **interface**. Custom controls must implement these methods; built-in controls already do.

Interface Methods

onAdd()
onAdd(map: Map): HTMLElement

Called when the control is added to the map.

Parameters:

map Map The map instance the control is being added to.
Returns: HTMLElement (The main container element for the control)
onRemove()
onRemove(map: Map): void

Called when the control is removed from the map. Should clean up DOM and event listeners.

Returns: void

2. NavigationControl 🧭

Provides buttons for zooming and for resetting the map's rotation and pitch (compass).

new gtswebsdkgl.NavigationControl(options?: NavigationControlOptions)

Creates a new NavigationControl instance.

The options below can be passed to the constructor to customize the control's appearance and functionality.

boolean

If true, the compass button (for resetting rotation/pitch) is visible. **Default:** true.

boolean

If true, the zoom in (+) and zoom out (-) buttons are visible. **Default:** true.

boolean

If true, the compass icon rotates and tilts to visualize the map's current rotation and pitch. **Default:** false.

import { NavigationControl } from 'gtswebsdkgl';

const nav = new NavigationControl({
  showCompass: false, // Only show zoom buttons
  visualizePitch: true
});
map.addControl(nav, 'top-right');

3. FullscreenControl 🖥️

Provides a button to toggle the map container into and out of fullscreen mode.

Constructor

new gtswebsdkgl.FullscreenControl(options?: FullscreenControlOptions)

Creates a new FullscreenControl instance.

Options (FullscreenControlOptions)

container
HTMLElement

The DOM element that should be made fullscreen. **Default:** The map container element.

Usage Example

const fsControl = new FullscreenControl();
map.addControl(fsControl, 'top-left');

4. GeolocateControl 📍

Uses the browser's **Geolocation API** to find and display the user's current location on the map. It typically displays a pulsing dot for the location and a circle indicating the accuracy.

Constructor

new gtswebsdkgl.GeolocateControl(options?: GeolocateControlOptions)

Creates a new GeolocateControl instance.

Options (GeolocateControlOptions)

Configuration options to control the behavior of the geolocation tracking and visualization.

positionOptions
Object

An object literal passed directly to the browser's Geolocation API's getCurrentPosition and watchPosition calls. Common properties include:

  • enableHighAccuracy: **boolean** (Default: `false`)
  • timeout: **number** (Maximum time in ms to wait for a position, Default: `6000`)
  • maximumAge: **number** (Maximum age in ms of a cached position, Default: `0`)

fitBoundsOptions
Object

An object literal passed to the map's fitBounds method when centering the map on the user's location. This allows you to set options like **padding** or **maxZoom**.
*Example:* { maxZoom: 15, duration: 1000 }

trackUserLocation
boolean

If true, the map will continuously track the user's position as it changes. **Default:** false.

showUserLocation
boolean

If true, the user location dot and accuracy circle are rendered on the map. **Default:** true.

showAccuracyCircle
boolean

If true, the accuracy circle is shown around the user location dot. **Default:** true.

Events

The GeolocateControl emits events that allow you to react to tracking status and results.

geolocate
Event (type: 'geolocate', data: GeolocationPosition)

Fired when a new **Geolocation Position** is successfully available. The event's data contains the GeolocationPosition object.

error
Event (type: 'error', data: GeolocationPositionError)

Fired when the Geolocation API returns an error (e.g., permission denied, timeout).

trackuserlocationstart
Event (type: 'trackuserlocationstart')

Fired when the control is activated to start continuously tracking the user's location.

trackuserlocationend
Event (type: 'trackuserlocationend')

Fired when the control is deactivated and stops tracking the user's location.

Usage Example

import { GeolocateControl } from 'gtswebsdkgl';

const geoControl = new GeolocateControl({
  positionOptions: { enableHighAccuracy: true },
  trackUserLocation: true
});

map.addControl(geoControl, 'bottom-right');

// Listen for successful location updates
geoControl.on('geolocate', (e) => {
  console.log('User located at:', e.coords.latitude, e.coords.longitude);
});

5. ScaleControl 📏

A **standard map control** that displays a scale bar indicating the current map distance relative to the screen distance.

Constructor

new gtswebsdkgl.ScaleControl(options?: ScaleControlOptions)

Creates a new ScaleControl instance.

Options (ScaleControlOptions)

maxWidth
number

The maximum width of the scale control in pixels. **Default:** 100.

unit
string

The unit of the scale. Must be one of 'imperial', 'metric', or 'nautical'. **Default:** 'metric'.

Usage Example

const scale = new ScaleControl({ unit: 'imperial' });
map.addControl(scale, 'bottom-left');

6. TerrainControl ⛰️

Provides a toggle button to enable or disable 3D terrain on the map, assuming a suitable **Raster DEM source** is configured on the map's style.

This control requires the map to have a **Terrain Source** added to its style to function.

Constructor

new gtswebsdkgl.TerrainControl(options?: TerrainControlOptions)

Creates a new TerrainControl instance.

Options (TerrainControlOptions)

sourceId
string

The ID of the terrain source that should be toggled by the control. **Required.**

exaggeration
number

The vertical exaggeration factor to apply when enabling terrain. **Default:** 1.0.

Usage Example

Assumes a terrain source with ID `'gts-terrain'` is available in the map's style.

// 1. Map must be initialized with the terrain source
// 2. Add the control to toggle it on/off
const terrain = new TerrainControl({
  sourceId: 'gts-terrain',
  exaggeration: 1.5
});
map.addControl(terrain, 'top-right');

7. AttributionControl (Map Option)

Displays the map's required attribution and copyright information (e.g., OpenStreetMap, data providers). The control is typically managed via the main MapOptions.

Management

The AttributionControl is added by default when initializing the map. Its visibility is controlled by the MapOptions properties:

attributionControl
boolean

If false, the AttributionControl is not added to the map. **Default:** true.

Manual Control

If attributionControl is set to false during Map initialization, you can manually add an AttributionControl instance, though it's rarely necessary.

// Initialize map without default control
const map = new Map({ target: 'map', attributionControl: false, ... });

// Manually add the control later (optional)
const attribution = new AttributionControl({ compact: true });
map.addControl(attribution, 'bottom-left');