UI Components

This page documents the user interface components provided by Mapbox GL JS. These components enhance map usability by adding interactive elements that allow users to navigate, locate themselves, display information, and more. For specific information about markers and popups, see Markers and Popups, for detailed control documentation, see Controls, and for interaction details, see Interaction and Events.

Overview of UI Components

Mapbox GL JS provides three main categories of UI components:

100%

Component Positioning System

UI components in Mapbox GL JS follow a structured positioning system that allows for precise placement on the map.

100%

CSS Positioning Elements

The map container includes eight positioning containers that determine where UI controls appear:

Position Class	Location	CSS Selector
Top	Top center	.mapboxgl-ctrl-top
Top Right	Upper right corner	.mapboxgl-ctrl-top-right
Right	Right center	.mapboxgl-ctrl-right
Bottom Right	Lower right corner	.mapboxgl-ctrl-bottom-right
Bottom	Bottom center	.mapboxgl-ctrl-bottom
Bottom Left	Lower left corner	.mapboxgl-ctrl-bottom-left
Left	Left center	.mapboxgl-ctrl-left

Built-in Controls

Mapbox GL JS provides several built-in controls that can be added to the map:

Navigation Control

The NavigationControl adds zoom and rotation buttons to the map. It is typically positioned in the top-left corner.

map.addControl(new mapboxgl.NavigationControl());

Key CSS classes:

• .mapboxgl-ctrl-zoom-in: Zoom in button
• .mapboxgl-ctrl-zoom-out: Zoom out button
• .mapboxgl-ctrl-compass: Compass button for resetting rotation

Geolocate Control

The GeolocateControl adds a button that uses the browser's geolocation API to locate and track the user on the map.

map.addControl(new mapboxgl.GeolocateControl({
    positionOptions: {
        enableHighAccuracy: true
    },
    trackUserLocation: true,
    showUserLocation: true,
    showUserHeading: true,
    fitBoundsOptions: {
        maxZoom: 20
    }
}));

Key CSS classes:

• .mapboxgl-ctrl-geolocate: Base class for the geolocate button
• .mapboxgl-ctrl-geolocate-active: Applied when actively tracking location
• .mapboxgl-ctrl-geolocate-background: Applied when tracking in background
• .mapboxgl-user-location-dot: User location indicator

Scale Control

The ScaleControl adds a distance scale indicator to the map, typically in the bottom-left corner.

map.addControl(new mapboxgl.ScaleControl());
// With options
map.addControl(new mapboxgl.ScaleControl({
    unit: 'nautical'
}));

Key CSS classes:

• .mapboxgl-ctrl-scale: The scale indicator

Fullscreen Control

The FullscreenControl adds a button to toggle fullscreen mode for the map.

map.addControl(new mapboxgl.FullscreenControl());

Key CSS classes:

• .mapboxgl-ctrl-fullscreen: Fullscreen button
• .mapboxgl-ctrl-shrink: Button when in fullscreen mode

Attribution Control

The AttributionControl displays attribution information for the map data. It's automatically added to maps by default.

Key CSS classes:

• .mapboxgl-ctrl-attrib: Container for attribution information
• .mapboxgl-ctrl-attrib-button: Toggle button for compact mode
• .mapboxgl-ctrl-attrib-inner: Container for attribution text

Creating Custom Controls

You can create custom controls by implementing the IControl interface, which requires onAdd and onRemove methods:

class CustomControl {
    onAdd(map) {
        this._map = map;
        this._container = document.createElement('div');
        this._container.className = 'mapboxgl-ctrl';
        // Add content and event handlers to this._container
        return this._container;
    }

    onRemove() {
        this._container.parentNode.removeChild(this._container);
        this._map = undefined;
    }
}

map.addControl(new CustomControl(), 'top-right');

Markers

Markers are visual indicators positioned at specific geographical coordinates on the map.

Basic Markers

const marker = new mapboxgl.Marker()
    .setLngLat([-77.03, 38.90])
    .addTo(map);

Key CSS classes:

• .mapboxgl-marker: Base class for markers

Custom Markers

You can customize markers with your own HTML elements:

const el = document.createElement('div');
el.className = 'custom-marker';
// Customize the element as needed

const marker = new mapboxgl.Marker(el)
    .setLngLat([-77.03, 38.90])
    .addTo(map);

User Location Markers

The GeolocateControl automatically adds a user location marker when activated:

Key CSS classes:

• .mapboxgl-user-location-dot: The user's location point
• .mapboxgl-user-location-accuracy-circle: Accuracy radius circle
• .mapboxgl-user-location-heading: Direction indicator

Popups

Popups display information in a floating container attached to a specific location or marker on the map.

Creating Popups

You can create popups in various ways:

// Stand-alone popup
const popup = new mapboxgl.Popup()
    .setLngLat(map.unproject(e.point))
    .setHTML("<h1>Hello World!</h1>")
    .addTo(map);

// Popup attached to a marker
const marker = new mapboxgl.Marker()
    .setLngLat([-77.03, 38.90])
    .setPopup(new mapboxgl.Popup().setHTML("<h1>Marker Popup</h1>"))
    .addTo(map);

// Popup in response to a map click
map.on('click', function(e) {
    new mapboxgl.Popup()
        .setLngLat(map.unproject(e.point))
        .setHTML("<h1>Click Location</h1>")
        .addTo(map);
});

Key CSS classes:

• .mapboxgl-popup: Base container for popups
• .mapboxgl-popup-content: Content container
• .mapboxgl-popup-close-button: Close button
• .mapboxgl-popup-tip: Directional pointer

Popup Anchoring

Popups can be anchored in different positions relative to their coordinates:

const popup = new mapboxgl.Popup({
    anchor: 'bottom' // Can be 'top', 'bottom', 'left', 'right', 'top-left', etc.
});

The CSS applies specific styling based on the anchor position:

.mapboxgl-popup-anchor-top,
.mapboxgl-popup-anchor-top-left,
.mapboxgl-popup-anchor-top-right {
    flex-direction: column;
}

.mapboxgl-popup-anchor-bottom,
.mapboxgl-popup-anchor-bottom-left,
.mapboxgl-popup-anchor-bottom-right {
    flex-direction: column-reverse;
}

Control Group Styling

Multiple controls can be grouped together with consistent styling using the .mapboxgl-ctrl-group class:

// These controls will appear grouped together
map.addControl(new mapboxgl.NavigationControl(), 'top-right');
map.addControl(new mapboxgl.GeolocateControl(), 'top-right');

Key CSS classes:

• .mapboxgl-ctrl-group: Container for grouped controls
• .mapboxgl-ctrl: Base class for all controls

Internationalization

Mapbox GL JS supports internationalization of UI components through locale strings:

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    locale: {
        'NavigationControl.ZoomIn': 'Zoom in',
        'NavigationControl.ZoomOut': 'Zoom out',
        'NavigationControl.ResetBearing': 'Reset bearing to north',
        'GeolocateControl.FindMyLocation': 'Find my location',
        'GeolocateControl.LocationNotAvailable': 'Location not available',
        'FullscreenControl.Enter': 'Enter fullscreen',
        'FullscreenControl.Exit': 'Exit fullscreen',
        'ScaleControl.Feet': 'ft',
        'ScaleControl.Meters': 'm'
        // Other locale strings...
    }
});

Default locale strings are defined in the library:

const defaultLocale = {
    'AttributionControl.ToggleAttribution': 'Toggle attribution',
    'FullscreenControl.Enter': 'Enter fullscreen',
    'FullscreenControl.Exit': 'Exit fullscreen',
    'GeolocateControl.FindMyLocation': 'Find my location',
    'GeolocateControl.LocationNotAvailable': 'Location not available',
    'LogoControl.Title': 'Mapbox homepage',
    'Map.Title': 'Map',
    'NavigationControl.ResetBearing': 'Reset bearing to north',
    'NavigationControl.ZoomIn': 'Zoom in',
    'NavigationControl.ZoomOut': 'Zoom out',
    'ScaleControl.Feet': 'ft',
    'ScaleControl.Meters': 'm',
    'ScaleControl.Kilometers': 'km',
    'ScaleControl.Miles': 'mi',
    'ScaleControl.NauticalMiles': 'nm',
    'ScrollZoomBlocker.CtrlMessage': 'Use ctrl + scroll to zoom the map',
    'ScrollZoomBlocker.CmdMessage': 'Use ⌘ + scroll to zoom the map',
    'TouchPanBlocker.Message': 'Use two fingers to move the map'
};

Interactive Behavior and Events

UI components can respond to various interaction events:

// Marker interaction
const marker = new mapboxgl.Marker()
    .setLngLat([-77.03, 38.90])
    .addTo(map);

marker.getElement().addEventListener('click', () => {
    console.log('Marker clicked!');
});

// Layer interaction
map.on('mouseenter', 'marker', function(e) {
    map.setFilter('marker-hover', ['==', 'name', e.features[0].properties.name]);
    map.getCanvas().style.cursor = 'pointer';
});

map.on('mouseleave', 'marker', function(e) {
    map.setFilter('marker-hover', ['==', 'name', '']);
    map.getCanvas().style.cursor = '';
});

Map elements have specific cursor styles for different interactive states:

.mapboxgl-canvas-container.mapboxgl-interactive,
.mapboxgl-ctrl-group button.mapboxgl-ctrl-compass {
    cursor: grab;
}

.mapboxgl-canvas-container.mapboxgl-interactive.mapboxgl-track-pointer {
    cursor: pointer;
}

.mapboxgl-canvas-container.mapboxgl-interactive:active,
.mapboxgl-ctrl-group button.mapboxgl-ctrl-compass:active {
    cursor: grabbing;
}

Cooperative Gestures and Blockers

Mapbox GL JS provides UI feedback when certain gestures are blocked or require modifiers:

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    cooperativeGestures: true
});

Key CSS classes:

• .mapboxgl-touch-pan-blocker: Shown when touch pan is blocked
• .mapboxgl-scroll-zoom-blocker: Shown when scroll zoom is blocked

Component System Integration

The following diagram shows how UI components integrate with the overall Mapbox GL JS architecture:

100%

The UI Components system in Mapbox GL JS provides a comprehensive suite of interactive elements that enhance map usability while maintaining a consistent look and feel. These components can be extensively customized and positioned to meet specific application requirements.