or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcontrols.mdevents.mdgeographic-utilities.mdindex.mdmap-core.mdui-components.md
tile.json

controls.mddocs/

Controls

Built-in UI controls for common map interactions including navigation, geolocation, attribution display, and other user interface elements that can be added to maps.

Capabilities

IControl Interface

All controls implement the IControl interface, which defines the basic lifecycle methods for map controls.

/**
 * Interface that all map controls must implement
 */
interface IControl {
  /**
   * Called when the control is added to a map
   * @param map - The map instance
   * @returns The control's DOM element
   */
  onAdd(map: Map): HTMLElement;
  
  /**
   * Called when the control is removed from a map
   */
  onRemove(): void;
  
  /**
   * Optional method to return the default position for the control
   */
  getDefaultPosition?(): ControlPosition;
}

type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

NavigationControl

Zoom in/out buttons and compass control for map navigation.

/**
 * Navigation control with zoom buttons and compass
 * @param options - Configuration options for the navigation control
 */
class NavigationControl implements IControl {
  constructor(options?: NavigationControlOptions);
  onAdd(map: Map): HTMLElement;
  onRemove(): void;
}

interface NavigationControlOptions {
  showCompass?: boolean;
  showZoom?: boolean;
  visualizePitch?: boolean;
}

Usage Examples:

import mapboxgl from 'mapbox-gl';

// Basic navigation control
const nav = new mapboxgl.NavigationControl();
map.addControl(nav, 'top-right');

// Navigation control with options
const customNav = new mapboxgl.NavigationControl({
  showCompass: true,
  showZoom: true,
  visualizePitch: true
});
map.addControl(customNav, 'top-left');

// Navigation control without compass
const zoomOnly = new mapboxgl.NavigationControl({
  showCompass: false,
  showZoom: true
});
map.addControl(zoomOnly, 'bottom-right');

GeolocateControl

GPS geolocation control that allows users to center the map on their current location.

/**
 * Geolocation control for GPS positioning
 * @param options - Configuration options for the geolocate control
 */
class GeolocateControl implements IControl {
  constructor(options?: GeolocateControlOptions);
  onAdd(map: Map): HTMLElement;
  onRemove(): void;
  
  /**
   * Trigger geolocation programmatically
   * @returns True if geolocation was triggered, false otherwise
   */
  trigger(): boolean;
}

interface GeolocateControlOptions {
  positionOptions?: PositionOptions;
  fitBoundsOptions?: FitBoundsOptions;
  trackUserLocation?: boolean;
  showAccuracyCircle?: boolean;
  showUserHeading?: boolean;
  showUserLocation?: boolean;
}

interface PositionOptions {
  enableHighAccuracy?: boolean;
  timeout?: number;
  maximumAge?: number;
}

Usage Examples:

import mapboxgl from 'mapbox-gl';

// Basic geolocate control
const geolocate = new mapboxgl.GeolocateControl();
map.addControl(geolocate, 'top-right');

// Geolocate with tracking enabled
const trackingGeolocate = new mapboxgl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true
  },
  trackUserLocation: true,
  showUserHeading: true,
  showAccuracyCircle: true
});
map.addControl(trackingGeolocate, 'top-right');

// Handle geolocate events
trackingGeolocate.on('geolocate', (e) => {
  console.log('User location:', e.coords.latitude, e.coords.longitude);
});

trackingGeolocate.on('error', (e) => {
  console.log('Geolocation error:', e.message);
});

// Trigger geolocation programmatically
document.getElementById('locate-btn').addEventListener('click', () => {
  trackingGeolocate.trigger();
});

AttributionControl

Control that displays attribution information for map data sources and Mapbox branding.

/**
 * Attribution control for displaying data source credits
 * @param options - Configuration options for the attribution control
 */
class AttributionControl implements IControl {
  constructor(options?: AttributionControlOptions);
  onAdd(map: Map): HTMLElement;
  onRemove(): void;
}

interface AttributionControlOptions {
  compact?: boolean;
  customAttribution?: string | string[];
}

Usage Examples:

import mapboxgl from 'mapbox-gl';

// Basic attribution control
const attribution = new mapboxgl.AttributionControl();
map.addControl(attribution, 'bottom-right');

// Compact attribution control
const compactAttribution = new mapboxgl.AttributionControl({
  compact: true
});
map.addControl(compactAttribution, 'bottom-right');

// Attribution with custom text
const customAttribution = new mapboxgl.AttributionControl({
  customAttribution: ['© My Company', '© Custom Data Provider']
});
map.addControl(customAttribution, 'bottom-right');

ScaleControl

Control that displays the map scale indicator.

/**
 * Scale control that shows map scale
 * @param options - Configuration options for the scale control
 */
class ScaleControl implements IControl {
  constructor(options?: ScaleControlOptions);
  onAdd(map: Map): HTMLElement;
  onRemove(): void;
}

interface ScaleControlOptions {
  maxWidth?: number;
  unit?: 'imperial' | 'metric' | 'nautical';
}

Usage Examples:

import mapboxgl from 'mapbox-gl';

// Basic scale control
const scale = new mapboxgl.ScaleControl();
map.addControl(scale, 'bottom-left');

// Scale control with imperial units
const imperialScale = new mapboxgl.ScaleControl({
  maxWidth: 100,
  unit: 'imperial'
});
map.addControl(imperialScale, 'bottom-left');

// Scale control with metric units
const metricScale = new mapboxgl.ScaleControl({
  maxWidth: 80,
  unit: 'metric'
});
map.addControl(metricScale, 'bottom-left');

FullscreenControl

Control that provides fullscreen toggle functionality.

/**
 * Fullscreen control for toggling fullscreen mode
 * @param options - Configuration options for the fullscreen control
 */
class FullscreenControl implements IControl {
  constructor(options?: FullscreenControlOptions);
  onAdd(map: Map): HTMLElement;
  onRemove(): void;
}

interface FullscreenControlOptions {
  container?: HTMLElement;
}

Usage Examples:

import mapboxgl from 'mapbox-gl';

// Basic fullscreen control
const fullscreen = new mapboxgl.FullscreenControl();
map.addControl(fullscreen, 'top-right');

// Fullscreen control with custom container
const customFullscreen = new mapboxgl.FullscreenControl({
  container: document.getElementById('map-container')
});
map.addControl(customFullscreen, 'top-right');

// Handle fullscreen events
map.on('fullscreenchange', () => {
  if (map.isFullscreen()) {
    console.log('Entered fullscreen mode');
  } else {
    console.log('Exited fullscreen mode');
  }
});

IndoorControl

Control for indoor mapping floor selection that presents the map's indoor floors when using indoor-enabled styles.

/**
 * Indoor control for floor selection in indoor maps
 * @experimental
 */
class IndoorControl implements IControl {
  constructor();
  onAdd(map: Map): HTMLElement;
  onRemove(): void;
  getDefaultPosition(): ControlPosition;
}

interface IndoorControlLevel {
  id: string;
  name: string;
  shortName: string;
  levelOrder: number;
}

interface IndoorControlModel {
  selectedFloorId: string;
  floors: IndoorControlLevel[];
}

Usage Examples:

import mapboxgl from 'mapbox-gl';

// Indoor control for floor selection
const indoor = new mapboxgl.IndoorControl();
map.addControl(indoor, 'top-left');

// Handle indoor update events
map.indoor.on('indoorupdate', (event) => {
  console.log('Indoor floors updated:', event.floors);
  console.log('Selected floor:', event.selectedFloorId);
});

// Indoor control automatically shows/hides based on indoor data availability
// The control displays floor buttons sorted by levelOrder

Custom Controls

You can create custom controls by implementing the IControl interface.

/**
 * Example custom control implementation
 */
class CustomControl implements IControl {
  private map: Map;
  private container: HTMLElement;
  
  onAdd(map: Map): HTMLElement {
    this.map = map;
    this.container = document.createElement('div');
    this.container.className = 'mapboxgl-ctrl mapboxgl-ctrl-group';
    
    const button = document.createElement('button');
    button.className = 'mapboxgl-ctrl-icon custom-ctrl-icon';
    button.type = 'button';
    button.title = 'Custom Action';
    button.onclick = this.handleClick.bind(this);
    
    this.container.appendChild(button);
    return this.container;
  }
  
  onRemove(): void {
    this.container.parentNode?.removeChild(this.container);
  }
  
  private handleClick(): void {
    // Custom control logic
    console.log('Custom control clicked');
  }
}

Usage Examples:

// Add custom control to map
const customControl = new CustomControl();
map.addControl(customControl, 'top-right');

// Reset view control
class ResetViewControl implements IControl {
  private map: Map;
  private container: HTMLElement;
  private initialOptions: { center: LngLatLike; zoom: number };
  
  constructor(initialOptions: { center: LngLatLike; zoom: number }) {
    this.initialOptions = initialOptions;
  }
  
  onAdd(map: Map): HTMLElement {
    this.map = map;
    this.container = document.createElement('div');
    this.container.className = 'mapboxgl-ctrl mapboxgl-ctrl-group';
    
    const button = document.createElement('button');
    button.className = 'mapboxgl-ctrl-icon';
    button.type = 'button';
    button.title = 'Reset View';
    button.innerHTML = '⌂';
    button.onclick = () => {
      this.map.flyTo({
        center: this.initialOptions.center,
        zoom: this.initialOptions.zoom
      });
    };
    
    this.container.appendChild(button);
    return this.container;
  }
  
  onRemove(): void {
    this.container.parentNode?.removeChild(this.container);
  }
}

// Usage
const resetControl = new ResetViewControl({
  center: [-74.006, 40.7128],
  zoom: 9
});
map.addControl(resetControl, 'top-left');

Control Management

// Methods available on the Map class for control management

/**
 * Add a control to the map
 * @param control - Control instance implementing IControl
 * @param position - Position where to place the control
 * @returns Map instance for chaining
 */
addControl(control: IControl, position?: ControlPosition): Map;

/**
 * Remove a control from the map
 * @param control - Control instance to remove
 * @returns Map instance for chaining
 */
removeControl(control: IControl): Map;

Usage Examples:

// Add multiple controls
const nav = new mapboxgl.NavigationControl();
const geolocate = new mapboxgl.GeolocateControl();
const scale = new mapboxgl.ScaleControl();

map.addControl(nav, 'top-right');
map.addControl(geolocate, 'top-right');
map.addControl(scale, 'bottom-left');

// Remove controls
map.removeControl(nav);
map.removeControl(geolocate);

// Add controls conditionally
if (window.navigator.geolocation) {
  map.addControl(new mapboxgl.GeolocateControl(), 'top-right');
}

// Control positioning
const positions: ControlPosition[] = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
positions.forEach((position, index) => {
  if (index < 2) {
    map.addControl(new mapboxgl.NavigationControl(), position);
  }
});