Controls System

Purpose and Scope

The Controls System provides user interface elements that are positioned over the map to enable user interaction and display information. Controls are visible widgets with fixed positions on screen that can involve user input (buttons) or be informational displays. This system manages the creation, positioning, rendering, and lifecycle of built-in UI controls like zoom buttons, attribution display, scale line, and overview map.

For information about user interactions with map content (drawing, selecting features), see Feature Editing Interactions. For overlays positioned at geographic coordinates, see Overlays and Positioning.

Control System Architecture

100%

Base Control Class

The Control class serves as the foundation for all UI controls in OpenLayers. It extends BaseObject and provides common functionality for DOM element management, map integration, and rendering lifecycle.

Core Properties and Methods

Property/Method	Purpose
element	The control's DOM container element
map_	Reference to the associated Map instance
target_	Custom target element for rendering
listenerKeys	Array of event listener keys for cleanup
setMap(map)	Attach/detach control to/from map
render(mapEvent)	Called on each map render cycle

Control Lifecycle

100%

Built-in Control Types

Information Display Controls

Attribution Control

Displays layer source attributions with collapsible functionality.

Key features:

• Collapsible display controlled by collapsible option
• Auto-collection of attributions from visible layers
• Support for custom attributions via attributions option
• XSS protection warning for dynamic content

100%

ScaleLine Control

Displays a scale bar or scale line showing map scale at current zoom level.

Configuration options:

• bar: Render as scalebar instead of line
• steps: Number of scalebar segments
• units: Display units (metric, imperial, nautical, degrees, us)
• dpi: Output device DPI for accurate scaling

MousePosition Control

Shows current mouse coordinates in specified projection and format.

Key features:

• Configurable coordinate format via coordinateFormat
• Projection transformation support
• Placeholder text when mouse leaves viewport
• World wrapping on global projections

Navigation Controls

Zoom Control

Provides zoom in/out buttons with customizable labels and styling.

100%

ZoomSlider Control

Slider-style zoom control with drag interaction.

Key features:

• Horizontal or vertical orientation auto-detection
• Drag interaction for continuous zoom changes
• Click-to-zoom functionality
• Animation support with configurable duration

Rotate Control

Button to reset map rotation to north with visual rotation indicator.

Features:

• Auto-hide when rotation is 0 (configurable)
• Animated rotation reset
• Visual compass indicator that rotates with map
• Custom reset function support

Advanced Controls

OverviewMap Control

Miniature overview map showing current viewport extent.

Complex features:

• Independent Map instance with separate view
• Box overlay showing main map extent
• Interactive dragging to pan main map
• Automatic extent adjustment and centering
• Collapsible with custom labels

100%

FullScreen Control

Enables full-screen mode using the Fullscreen API.

Features:

• Browser compatibility detection
• Custom source element support
• Keyboard access option
• Event dispatching for fullscreen state changes

Control Integration with Map

Controls integrate with the Map through several mechanisms:

DOM Container Integration

Controls are added to specific DOM containers managed by the Map:

100%

Render Cycle Integration

Controls participate in the map's render cycle through the render() method:

1. Map triggers MapEventType.POSTRENDER
2. Control's render(mapEvent) method called
3. Control updates its DOM based on current map state
4. Process repeats on each frame

Event Listener Management

Controls use listenerKeys array to track event listeners for proper cleanup:

100%

Control Configuration and Defaults

The control system provides a defaults() function that creates a standard set of controls for most mapping applications. This can be customized by excluding certain controls or adding additional ones.

Example usage patterns from the codebase:

• defaultControls() - Standard set of controls
• defaultControls({attribution: false}) - Exclude attribution
• defaultControls().extend([customControl]) - Add custom controls