---
title: "ScaleControl | JavaScript maps SDK"
description: "Documentation for MapTiler SDK"
---

> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.

# Class ScaleControl`Maptiler`

A `ScaleControl` control displays the ratio of a distance on the map to the corresponding distance on the ground.

#### Example[](#example)

```typescript
let scale = new ScaleControl({
    maxWidth: 80,
    unit: 'imperial'
});
map.addControl(scale);

scale.setUnit('metric');
```

#### Hierarchy ([View Summary](https://docs.maptiler.com/sdk-js/api-reference/hierarchy/#ScaleControl))

-   [ScaleControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/)
    -   ScaleControl

##### Index

### Constructors[](#constructors)

[constructor](#constructor)

### Properties[](#properties)

[options](#options) [setUnit](#setunit)

### Methods[](#methods)

[getDefaultPosition](#getdefaultposition) [onAdd](#onadd) [onRemove](#onremove)

## Constructors[](#constructors-1)

### constructor[](#constructor)

-   new ScaleControl(options?: [ScaleControlOptions](https://docs.maptiler.com/sdk-js/api-reference/types/ScaleControlOptions/)): ScaleControl[](#constructorscalecontrol)
    
    #### Parameters
    
    -   `Optional`options: [ScaleControlOptions](https://docs.maptiler.com/sdk-js/api-reference/types/ScaleControlOptions/)
        
        the control's options
        
    
    #### Returns ScaleControl
    
    Inherited from [ScaleControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/).[constructor](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/#constructor)
    

## Properties[](#properties-1)

### options[](#options)

options: [ScaleControlOptions](https://docs.maptiler.com/sdk-js/api-reference/types/ScaleControlOptions/)

Inherited from [ScaleControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/).[options](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/#options)

### setUnit[](#setunit)

setUnit: (unit: [Unit](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.Unit/)) \=> void

Set the scale's unit of the distance

#### Type Declaration

-   -   (unit: [Unit](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.Unit/)): void
    -   #### Parameters
        
        -   unit: [Unit](https://docs.maptiler.com/sdk-js/api-reference/types/Externals.Unit/)
            
            Unit of the distance (`'imperial'`, `'metric'` or `'nautical'`).
            
        
        #### Returns void
        

Inherited from [ScaleControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/).[setUnit](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/#setunit)

## Methods[](#methods-1)

### getDefaultPosition[](#getdefaultposition)

-   getDefaultPosition(): [ControlPosition](https://docs.maptiler.com/sdk-js/api-reference/types/ControlPosition/)[](#getdefaultposition-1)
    
    Optionally provide a default position for this control. If this method is implemented and [Map.addControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/#addcontrol) is called without the `position` parameter, the value returned by getDefaultPosition will be used as the control's position.
    
    #### Returns [ControlPosition](https://docs.maptiler.com/sdk-js/api-reference/types/ControlPosition/)
    
    a control position, one of the values valid in addControl.
    
    Inherited from [ScaleControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/).[getDefaultPosition](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/#getdefaultposition)
    

### `Maptiler`onAdd[](#onadd)

-   onAdd(map: [MapLibreMap](https://docs.maptiler.com/sdk-js/api-reference/classes/MapLibreMap/) | [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/)): [HTMLElement](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.HTMLElement/)[](#onadd-1)
    
    Register a control on the map and give it a chance to register event listeners and resources. This method is called by [Map.addControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/#addcontrol) internally.
    
    #### Parameters
    
    -   map: [MapLibreMap](https://docs.maptiler.com/sdk-js/api-reference/classes/MapLibreMap/) | [Map](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/)
        
        the Map this control will be added to
        
    
    #### Returns [HTMLElement](https://docs.maptiler.com/sdk-js/api-reference/interfaces/Externals.HTMLElement/)
    
    The control's container element. This should be created by the control and returned by onAdd without being attached to the DOM: the map will insert the control's element into the DOM as necessary.
    
    Overrides [ScaleControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/).[onAdd](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/#onadd)
    

### onRemove[](#onremove)

-   onRemove(): void[](#onremove-1)
    
    Unregister a control on the map and give it a chance to detach event listeners and resources. This method is called by [Map.removeControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Map/#removecontrol) internally.
    
    #### Returns void
    
    Inherited from [ScaleControl](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/).[onRemove](https://docs.maptiler.com/sdk-js/api-reference/classes/Externals.ScaleControl/#onremove)