0
# Controls & UI
1

2
User interface controls and overlays for map interaction including navigation controls, information displays, and custom DOM element positioning.
3

4
## Capabilities
5

6
### Base Control Class
7

8
Foundation class for all map controls with DOM element management.
9

10
```typescript { .api }
11
/**
12
 * Base control class for map UI elements
13
 * @param options - Control configuration options
14
 */
15
class Control {
16
  constructor(options: ControlOptions);
17
  
18
  /** Get the control element */
19
  getElement(): HTMLElement;
20
  /** Set the control element */
21
  setElement(element: HTMLElement): void;
22
  
23
  /** Get the map */
24
  getMap(): Map | null;
25
  /** Set the map (called automatically when added) */
26
  setMap(map: Map | null): void;
27
  
28
  /** Set the target for rendering the control */
29
  setTarget(target: HTMLElement | string | undefined): void;
30
  
31
  /** Render the control */
32
  render(mapEvent: MapEvent): void;
33
}
34

35
interface ControlOptions {
36
  /** DOM element for the control */
37
  element?: HTMLElement;
38
  /** Function called on render */
39
  render?: (mapEvent: MapEvent) => void;
40
  /** Target element or ID */
41
  target?: HTMLElement | string;
42
}
43
```
44

45
### Navigation Controls
46

47
Standard controls for map navigation and zoom operations.
48

49
```typescript { .api }
50
/**
51
 * Zoom in/out buttons control
52
 * @param options - Zoom control configuration
53
 */
54
class Zoom extends Control {
55
  constructor(options?: ZoomOptions);
56
}
57

58
interface ZoomOptions extends ControlOptions {
59
  /** Animation duration in milliseconds */
60
  duration?: number;
61
  /** CSS class for zoom in button */
62
  className?: string;
63
  /** Text/HTML for zoom in button */
64
  zoomInLabel?: string | HTMLElement;
65
  /** Text/HTML for zoom out button */
66
  zoomOutLabel?: string | HTMLElement;
67
  /** Title for zoom in button */
68
  zoomInTipLabel?: string;
69
  /** Title for zoom out button */
70
  zoomOutTipLabel?: string;
71
  /** Zoom delta per click */
72
  delta?: number;
73
}
74

75
/**
76
 * Zoom slider control
77
 * @param options - Zoom slider configuration
78
 */
79
class ZoomSlider extends Control {
80
  constructor(options?: ZoomSliderOptions);
81
}
82

83
interface ZoomSliderOptions extends ControlOptions {
84
  /** Animation duration */
85
  duration?: number;
86
  /** Maximum resolution for slider */
87
  maxResolution?: number;
88
  /** Minimum resolution for slider */
89
  minResolution?: number;
90
}
91

92
/**
93
 * Zoom to extent control
94
 * @param options - Zoom to extent configuration
95
 */
96
class ZoomToExtent extends Control {
97
  constructor(options?: ZoomToExtentOptions);
98
}
99

100
interface ZoomToExtentOptions extends ControlOptions {
101
  /** CSS class name */
102
  className?: string;
103
  /** Target extent to zoom to */
104
  extent?: Extent;
105
  /** Button label */
106
  label?: string | HTMLElement;
107
  /** Button title */
108
  tipLabel?: string;
109
}
110

111
/**
112
 * Rotation control for resetting map rotation
113
 * @param options - Rotate control configuration
114
 */
115
class Rotate extends Control {
116
  constructor(options?: RotateOptions);
117
}
118

119
interface RotateOptions extends ControlOptions {
120
  /** CSS class name */
121
  className?: string;
122
  /** Button label */
123
  label?: string | HTMLElement;
124
  /** Button title */
125
  tipLabel?: string;
126
  /** Animation duration */
127
  duration?: number;
128
  /** Auto-hide when rotation is 0 */
129
  autoHide?: boolean;
130
  /** Function to render rotation */
131
  render?: (mapEvent: MapEvent) => void;
132
  /** Function to reset rotation */
133
  resetNorth?: () => void;
134
}
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
import { Zoom, ZoomSlider, ZoomToExtent, Rotate } from 'ol/control';
141
import { defaults as defaultControls } from 'ol/control';
142

143
// Create individual controls
144
const zoomControl = new Zoom({
145
  zoomInLabel: '+',
146
  zoomOutLabel: '−',
147
  duration: 250
148
});
149

150
const rotateControl = new Rotate({
151
  autoHide: false,
152
  label: '⇧'
153
});
154

155
const zoomToExtentControl = new ZoomToExtent({
156
  extent: [0, 0, 1000000, 1000000],
157
  label: 'E'
158
});
159

160
// Add controls to map
161
const map = new Map({
162
  controls: defaultControls().extend([
163
    rotateControl,
164
    zoomToExtentControl
165
  ])
166
});
167

168
// Add control after map creation
169
map.addControl(new ZoomSlider());
170
```
171

172
### Information Display Controls
173

174
Controls for displaying map information and metadata.
175

176
```typescript { .api }
177
/**
178
 * Attribution control for displaying layer attributions
179
 * @param options - Attribution configuration
180
 */
181
class Attribution extends Control {
182
  constructor(options?: AttributionOptions);
183
  
184
  /** Get attributions */
185
  getAttributions(): string[];
186
  /** Set attributions */
187
  setAttributions(attributions: string[]): void;
188
  
189
  /** Set collapsible state */
190
  setCollapsible(collapsible: boolean): void;
191
  /** Set collapsed state */
192
  setCollapsed(collapsed: boolean): void;
193
}
194

195
interface AttributionOptions extends ControlOptions {
196
  /** CSS class name */
197
  className?: string;
198
  /** Target for attributions */
199
  target?: HTMLElement | string;
200
  /** Collapsible attributions */
201
  collapsible?: boolean;
202
  /** Initially collapsed */
203
  collapsed?: boolean;
204
  /** Button label for collapsed state */
205
  label?: string | HTMLElement;
206
  /** Expand button title */
207
  expandClassName?: string;
208
  /** Collapse button title */
209
  collapseLabel?: string | HTMLElement;
210
  /** Collapse button title */
211
  tipLabel?: string;
212
}
213

214
/**
215
 * Scale line control for showing map scale
216
 * @param options - Scale line configuration
217
 */
218
class ScaleLine extends Control {
219
  constructor(options?: ScaleLineOptions);
220
  
221
  /** Get current units */
222
  getUnits(): Units;
223
  /** Set units to display */
224
  setUnits(units: Units): void;
225
}
226

227
interface ScaleLineOptions extends ControlOptions {
228
  /** CSS class name */
229
  className?: string;
230
  /** Minimum width in pixels */
231
  minWidth?: number;
232
  /** Units for scale */
233
  units?: Units;
234
  /** Show both metric and imperial */
235
  bar?: boolean;
236
  /** Text rendering */
237
  text?: boolean;
238
  /** DPI for calculations */
239
  dpi?: number;
240
}
241

242
/**
243
 * Mouse position control for displaying cursor coordinates
244
 * @param options - Mouse position configuration
245
 */
246
class MousePosition extends Control {
247
  constructor(options?: MousePositionOptions);
248
  
249
  /** Get coordinate format function */
250
  getCoordinateFormat(): CoordinateFormat;
251
  /** Set coordinate format function */
252
  setCoordinateFormat(format: CoordinateFormat): void;
253
  
254
  /** Get projection */
255
  getProjection(): Projection;
256
  /** Set projection */
257
  setProjection(projection: ProjectionLike): void;
258
}
259

260
interface MousePositionOptions extends ControlOptions {
261
  /** CSS class name */
262
  className?: string;
263
  /** Coordinate format function */
264
  coordinateFormat?: CoordinateFormat;
265
  /** Projection for coordinates */
266
  projection?: ProjectionLike;
267
  /** Placeholder text */
268
  placeholder?: string;
269
  /** Undefinedhtml for no coordinates */
270
  undefinedHTML?: string;
271
}
272
```
273

274
**Usage Examples:**
275

276
```typescript
277
import { Attribution, ScaleLine, MousePosition } from 'ol/control';
278
import { createStringXY } from 'ol/coordinate';
279
import { toLonLat } from 'ol/proj';
280

281
// Attribution control
282
const attribution = new Attribution({
283
  collapsible: true,
284
  collapsed: false
285
});
286

287
// Scale line control
288
const scaleLine = new ScaleLine({
289
  units: 'metric',
290
  bar: true,
291
  text: true
292
});
293

294
// Mouse position control
295
const mousePosition = new MousePosition({
296
  coordinateFormat: createStringXY(4),
297
  projection: 'EPSG:4326',
298
  placeholder: 'Mouse over map for coordinates'
299
});
300

301
// Add to map
302
map.addControl(attribution);
303
map.addControl(scaleLine);
304
map.addControl(mousePosition);
305
```
306

307
### Overview Map Control
308

309
Minimap control for displaying map context.
310

311
```typescript { .api }
312
/**
313
 * Overview map (minimap) control
314
 * @param options - Overview map configuration
315
 */
316
class OverviewMap extends Control {
317
  constructor(options?: OverviewMapOptions);
318
  
319
  /** Get the overview map */
320
  getOverviewMap(): Map;
321
  /** Get collapsed state */
322
  getCollapsed(): boolean;
323
  /** Set collapsed state */
324
  setCollapsed(collapsed: boolean): void;
325
  
326
  /** Get collapsible state */
327
  getCollapsible(): boolean;
328
  /** Set collapsible state */
329
  setCollapsible(collapsible: boolean): void;
330
}
331

332
interface OverviewMapOptions extends ControlOptions {
333
  /** Initially collapsed */
334
  collapsed?: boolean;
335
  /** Can be collapsed/expanded */
336
  collapsible?: boolean;
337
  /** CSS class name */
338
  className?: string;
339
  /** Layers for overview map */
340
  layers?: Layer[] | Collection<Layer>;
341
  /** Target element */
342
  target?: HTMLElement | string;
343
  /** Button label for collapsed state */
344
  label?: string | HTMLElement;
345
  /** Collapse button label */
346
  collapseLabel?: string | HTMLElement;
347
  /** Expand button title */
348
  tipLabel?: string;
349
  /** View for overview map */
350
  view?: View;
351
  /** Rotation follows main map */
352
  rotateWithView?: boolean;
353
}
354
```
355

356
**Usage Examples:**
357

358
```typescript
359
import OverviewMap from 'ol/control/OverviewMap';
360
import TileLayer from 'ol/layer/Tile';
361
import OSM from 'ol/source/OSM';
362

363
// Create overview map control
364
const overviewMap = new OverviewMap({
365
  collapsed: false,
366
  collapsible: true,
367
  layers: [
368
    new TileLayer({
369
      source: new OSM()
370
    })
371
  ],
372
  view: new View({
373
    projection: 'EPSG:3857'
374
  })
375
});
376

377
map.addControl(overviewMap);
378
```
379

380
### Fullscreen Control
381

382
Control for toggling fullscreen mode.
383

384
```typescript { .api }
385
/**
386
 * Fullscreen toggle control
387
 * @param options - Fullscreen configuration
388
 */
389
class FullScreen extends Control {
390
  constructor(options?: FullScreenOptions);
391
}
392

393
interface FullScreenOptions extends ControlOptions {
394
  /** CSS class name */
395
  className?: string;
396
  /** Button label for entering fullscreen */
397
  label?: string | HTMLElement;
398
  /** Button label for exiting fullscreen */
399
  labelActive?: string | HTMLElement;
400
  /** Button title for entering fullscreen */
401
  tipLabel?: string;
402
  /** Keys for keyboard shortcuts */
403
  keys?: boolean;
404
  /** Source element for fullscreen */
405
  source?: HTMLElement | string;
406
}
407
```
408

409
### Overlay Class
410

411
DOM elements positioned at geographic coordinates.
412

413
```typescript { .api }
414
/**
415
 * Overlay for positioning DOM elements on the map
416
 * @param options - Overlay configuration
417
 */
418
class Overlay {
419
  constructor(options: OverlayOptions);
420
  
421
  /** Get the DOM element */
422
  getElement(): HTMLElement | undefined;
423
  /** Set the DOM element */
424
  setElement(element: HTMLElement | undefined): void;
425
  
426
  /** Get the map */
427
  getMap(): Map | null;
428
  /** Set the map */
429
  setMap(map: Map | null): void;
430
  
431
  /** Get the offset */
432
  getOffset(): number[];
433
  /** Set the offset */
434
  setOffset(offset: number[]): void;
435
  
436
  /** Get the position */
437
  getPosition(): Coordinate | undefined;
438
  /** Set the position */
439
  setPosition(position: Coordinate | undefined): void;
440
  
441
  /** Get positioning */
442
  getPositioning(): OverlayPositioning;
443
  /** Set positioning */
444
  setPositioning(positioning: OverlayPositioning): void;
445
  
446
  /** Pan map to show overlay */
447
  panIntoView(options?: PanIntoViewOptions): void;
448
}
449

450
interface OverlayOptions {
451
  /** DOM element to overlay */
452
  element?: HTMLElement;
453
  /** Map to add overlay to */
454
  map?: Map;
455
  /** Pixel offset */
456
  offset?: number[];
457
  /** Geographic position */
458
  position?: Coordinate;
459
  /** How element is positioned relative to position */
460
  positioning?: OverlayPositioning;
461
  /** Stop event propagation */
462
  stopEvent?: boolean;
463
  /** Insert first in overlay collection */
464
  insertFirst?: boolean;
465
  /** Auto-pan when position is set */
466
  autoPan?: boolean | PanIntoViewOptions;
467
  /** CSS class name */
468
  className?: string;
469
}
470

471
type OverlayPositioning = 
472
  | 'bottom-left' | 'bottom-center' | 'bottom-right'
473
  | 'center-left' | 'center-center' | 'center-right'
474
  | 'top-left' | 'top-center' | 'top-right';
475

476
interface PanIntoViewOptions {
477
  /** Animation */
478
  animation?: PanOptions;
479
  /** Margin around overlay */
480
  margin?: number;
481
}
482
```
483

484
**Usage Examples:**
485

486
```typescript
487
import Overlay from 'ol/Overlay';
488

489
// Create popup overlay
490
const popup = document.createElement('div');
491
popup.className = 'ol-popup';
492
popup.innerHTML = '<div class="popup-content">Hello World!</div>';
493

494
const overlay = new Overlay({
495
  element: popup,
496
  positioning: 'bottom-center',
497
  stopEvent: false,
498
  offset: [0, -50],
499
  autoPan: {
500
    animation: {
501
      duration: 250
502
    }
503
  }
504
});
505

506
// Add to map
507
map.addOverlay(overlay);
508

509
// Position at coordinate
510
overlay.setPosition([0, 0]);
511

512
// Listen for map clicks to show popup
513
map.on('click', (event) => {
514
  const coordinate = event.coordinate;
515
  overlay.setPosition(coordinate);
516
});
517
```
518

519
### Default Controls
520

521
Default control configuration for typical map usage.
522

523
```typescript { .api }
524
/**
525
 * Create default map controls
526
 * @param options - Configuration for default controls
527
 */
528
function defaults(options?: DefaultsOptions): Collection<Control>;
529

530
interface DefaultsOptions {
531
  /** Include attribution control */
532
  attribution?: boolean;
533
  /** Attribution control options */
534
  attributionOptions?: AttributionOptions;
535
  /** Include rotate control */
536
  rotate?: boolean;
537
  /** Rotate control options */
538
  rotateOptions?: RotateOptions;
539
  /** Include zoom control */
540
  zoom?: boolean;
541
  /** Zoom control options */
542
  zoomOptions?: ZoomOptions;
543
}
544
```
545

546
**Usage Examples:**
547

548
```typescript
549
import { defaults as defaultControls } from 'ol/control';
550

551
// Use default controls
552
const controls = defaultControls({
553
  attribution: true,
554
  zoom: true,
555
  rotate: false
556
});
557

558
// Create map with custom control configuration
559
const map = new Map({
560
  target: 'map',
561
  controls: controls,
562
  layers: [layer],
563
  view: view
564
});
565
```
566

567
## Types
568

569
```typescript { .api }
570
type CoordinateFormat = (coordinate?: Coordinate) => string;
571
type Units = 'degrees' | 'imperial' | 'us' | 'nautical' | 'metric';
572
```