---
title: "Change map styles | JavaScript maps SDK"
description: "Switch between built-in and custom map styles dynamically."
---

# Change map styles

This tutorial demonstrates the process of altering map styles, allowing users to seamlessly transition between the built-in maps and their customized maps. Explore the selection of pre-designed styles available in MapTiler’s library by referring to the [list of built-in styles](https://docs.maptiler.com/sdk-js/api/map-styles/#mapstylelist).

MapTiler provides a wide range of predefined styles, enabling users to customize their maps to suit their specific preferences. Additionally, you have the option to create a completely 100% customized map using [MapTiler’s Map Designer tool](https://www.maptiler.com/cloud/customize/).

Using the built-in styles and their variants defined in the SDK (`maptilersdk.MapStyle`) has several advantages such as:

-   If we make an update to a style, you won’t have to modify your codebase. Always use the latest version of styles.
-   They are easier to remember, no need to type along the style URL. No more putting the API key in every URL.
-   Code completion: reducing typos and other common mistakes.

The built-in styles generally define a purpose for which this style is the most relevant: **street navigation, outdoor adventure, minimalist dashboard**, etc. Then, each style offers a range of **variants** that contain the same level of information and have the same purpose but use different color schemes like **dark, light**, etc.

## NPM module setup

1.  Install the npm package.
    
    ```bash
    npm install --save @maptiler/sdk
    ```
    
2.  Include the CSS file.
    
    If you have a bundler that can handle CSS, you can `import` the CSS
    
    ```js
    import "@maptiler/sdk/dist/maptiler-sdk.css";
    ```
    
    or include it with a `<link />` in the head of the document via the CDN
    
    ```html
    <link href='https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.css' rel='stylesheet' />
    ```
    
3.  Include the following code in your JavaScript file (Example: app.js).
    
    ```js
    import * as maptilersdk from '@maptiler/sdk';
    
     maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
     const map = new maptilersdk.Map({
       container: 'map', // container's id or the HTML element to render the map
       style: maptilersdk.MapStyle.STREETS,
          
       center: [11.5786, 48.0968], // starting position [lng, lat]
       zoom: 10, // starting zoom
          
     });
    ```
    
4.  Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [secure the key](https://docs.maptiler.com/guides/credentials/api-key/#secure-key) before you publish it.
    
5.  The next is up to you. You can center your map wherever you desire (modifying the `starting position`) and set an appropriate zoom level (modifying the `starting zoom`) to match your users’ needs. Additionally, you can change the map’s look (by updating the `source URL`); choose from a range of visually appealing map styles from our extensive [MapTiler standard maps](https://cloud.maptiler.com/maps/), or create your own to truly differentiate your application.
    
6.  Change the map style to a hybrid satellite images.
    
    ```js
    map.setStyle(MapStyle.STREETS.DARK);
    ```
    
7.  Create a selector to change the map style. In this example we will use some of the build-in styles. See the full [list of styles](https://docs.maptiler.com/sdk-js/api/map-styles/#mapstylelist). Copy the following code into your HTML file.
    
    ```html
    <select class="mapstyles-select">
       <optgroup label="Navigation and city exploration">
         <option value="STREETS">STREETS</option>
         <option value="STREETS.DARK" selected>STREETS.DARK</option>
         <option value="STREETS.LIGHT">STREETS.LIGHT</option>
         <option value="STREETS.PASTEL">STREETS.PASTEL</option>
       </optgroup>
       <option value="OUTDOOR">OUTDOOR</option>
       <option value="WINTER">WINTER</option>
       <option value="SATELLITE">SATELLITE</option>
       <option value="HYBRID">HYBRID</option>
       <optgroup label="Data visualization">
         <option value="DATAVIZ">DATAVIZ</option>
         <option value="DATAVIZ.DARK">DATAVIZ.DARK</option>
         <option value="DATAVIZ.LIGHT">DATAVIZ.LIGHT</option>
       </optgroup>
       <option value="YOUR_CUSTOM_MAP_ID_1">Custom map name 1</option>
       <option value="YOUR_CUSTOM_MAP_ID_2">Custom map name 2</option>
     </select>
    ```
    
8.  Change the style when the user select one style.
    
    ```js
    document.querySelector('.mapstyles-select').addEventListener('change', (e) => {
       const style_code = e.target.value.split(".");
       style_code.length === 2 ? 
         map.setStyle(maptilersdk.MapStyle[style_code[0]][style_code[1]]) : 
         map.setStyle(maptilersdk.MapStyle[style_code[0]] || style_code[0]); 
     });
    ```
    
9.  Create the layer selector style. Add the selector style to your stylesheet.
    
    ```css
    .mapstyles-select {
       position: relative;
       top: 5px;
       left: 5px;
       z-index: 1000;
     }
    ```
    

## Basic JavaScript setup

1.  Copy the following code, paste it into your favorite text editor, and save it as a `.html` file.
    
    ```html
    <!DOCTYPE html>
     <html lang="en">
     <head>
       <meta charset="UTF-8">
       <meta name="viewport" content="width=device-width, initial-scale=1.0">
       <title>How to change map styles</title>
       <script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.umd.min.js"></script>
       <link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.css" rel="stylesheet" />
       <style>
         body { margin: 0; padding: 0; }
         #map { position: absolute; top: 0; bottom: 0; width: 100%; }
       </style>
     </head>
     <body>
       <div id="map"></div>
       <script>
           maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';      
           const map = new maptilersdk.Map({
             container: 'map', // container's id or the HTML element to render the map
             style: maptilersdk.MapStyle.STREETS,
                
             center: [11.5786, 48.0968], // starting position [lng, lat]
             zoom: 10, // starting zoom
                
           });
       </script>
     </body>
     </html>
    ```
    
2.  Replace `YOUR_MAPTILER_API_KEY_HERE` with [your own API key](https://cloud.maptiler.com/account/keys/). Make sure to [secure the key](https://docs.maptiler.com/guides/credentials/api-key/#secure-key) before you publish it.
    
3.  The next is up to you. You can center your map wherever you desire (modifying the `starting position`) and set an appropriate zoom level (modifying the `starting zoom`) to match your users’ needs. Additionally, you can change the map’s look (by updating the `source URL`); choose from a range of visually appealing map styles from our extensive [MapTiler standard maps](https://cloud.maptiler.com/maps/), or create your own to truly differentiate your application.
    
4.  Change the map style to a hybrid satellite images.
    
    ```js
    map.setStyle(MapStyle.STREETS.DARK);
    ```
    
5.  Create a selector to change the map style. In this example we will use some of the build-in styles. See the full [list of styles](https://docs.maptiler.com/sdk-js/api/map-styles/#mapstylelist). Copy the following code into your HTML file.
    
    ```html
    <select class="mapstyles-select">
       <optgroup label="Navigation and city exploration">
         <option value="STREETS">STREETS</option>
         <option value="STREETS.DARK" selected>STREETS.DARK</option>
         <option value="STREETS.LIGHT">STREETS.LIGHT</option>
         <option value="STREETS.PASTEL">STREETS.PASTEL</option>
       </optgroup>
       <option value="OUTDOOR">OUTDOOR</option>
       <option value="WINTER">WINTER</option>
       <option value="SATELLITE">SATELLITE</option>
       <option value="HYBRID">HYBRID</option>
       <optgroup label="Data visualization">
         <option value="DATAVIZ">DATAVIZ</option>
         <option value="DATAVIZ.DARK">DATAVIZ.DARK</option>
         <option value="DATAVIZ.LIGHT">DATAVIZ.LIGHT</option>
       </optgroup>
       <option value="YOUR_CUSTOM_MAP_ID_1">Custom map name 1</option>
       <option value="YOUR_CUSTOM_MAP_ID_2">Custom map name 2</option>
     </select>
    ```
    
6.  Change the style when the user select one style.
    
    ```js
    document.querySelector('.mapstyles-select').addEventListener('change', (e) => {
       const style_code = e.target.value.split(".");
       style_code.length === 2 ? 
         map.setStyle(maptilersdk.MapStyle[style_code[0]][style_code[1]]) : 
         map.setStyle(maptilersdk.MapStyle[style_code[0]] || style_code[0]); 
     });
    ```
    
7.  Create the layer selector style. Add the selector style to your stylesheet.
    
    ```css
    .mapstyles-select {
       position: relative;
       top: 5px;
       left: 5px;
       z-index: 1000;
     }
    ```
    

### Complete source code

```html
<!DOCTYPE html>
<html>

<head>
  <meta charset="utf-8" />
  <title>Display a map</title>
  <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
  <script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.umd.min.js"></script>
  <link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.css" rel="stylesheet" />
  <style>
    body { 
      margin: 0;
      padding: 0;
    }

    #map {
      position: absolute;
      top: 0;
      bottom: 0;
      width: 100%;
    }

    .mapstyles-select {
      position: relative;
      top: 5px;
      left: 5px;
      z-index: 1000;
    }
  </style>
</head>

<body>
  <div id="map">
    
  </div>
  <select class="mapstyles-select">
    <optgroup label="Navigation and city exploration">
      <option value="STREETS">STREETS</option>
      <option value="STREETS.DARK" selected>STREETS.DARK</option>
      <option value="STREETS.LIGHT">STREETS.LIGHT</option>
      <option value="STREETS.PASTEL">STREETS.PASTEL</option>
    </optgroup>
    <option value="OUTDOOR">OUTDOOR</option>
    <option value="WINTER">WINTER</option>
    <option value="SATELLITE">SATELLITE</option>
    <option value="HYBRID">HYBRID</option>
    <optgroup label="Data visualization">
      <option value="DATAVIZ">DATAVIZ</option>
      <option value="DATAVIZ.DARK">DATAVIZ.DARK</option>
      <option value="DATAVIZ.LIGHT">DATAVIZ.LIGHT</option>
    </optgroup>
    <option value="e4e704fd-bdaa-4a54-a6d5-50f1b07d9d68">Coffee</option>
    <option value="f38285f4-f75f-486a-9127-0cc7a7358ae6">Beer</option>
  </select>
  <script>
    maptilersdk.config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
    const map = new maptilersdk.Map({
      container: 'map', // container id
      style: maptilersdk.MapStyle.STREETS.DARK,
      center: [11.5786, 48.0968], // starting position [lng, lat]
      zoom: 10, // starting zoom
    });
    document.querySelector('.mapstyles-select').addEventListener('change', (e) => {
      const style_code = e.target.value.split(".");
      style_code.length === 2 ? 
        map.setStyle(maptilersdk.MapStyle[style_code[0]][style_code[1]]) : 
        map.setStyle(maptilersdk.MapStyle[style_code[0]] || style_code[0]); 
    });
  </script>
</body>

</html>
```

## Learn more

If you want to switch between built-in styles see this example [Built-in map styles](../built-in-styles/).

Check out this tutorial [How to display a style switcher control](../control-style-switcher/) to learn how to create a visual style switcher control.

## Related examples

### [Built-in map styles](https://docs.maptiler.com/sdk-js/examples/built-in-styles/)

Tutorials

Easily create beautiful maps using reliable built-in styles.

### [Style switcher](https://docs.maptiler.com/sdk-js/examples/control-style-switcher/)

Tutorials

Add a style switcher control to your map.

### [Set dark mode based on system settings](https://docs.maptiler.com/sdk-js/examples/style-by-settings/)

Examples

Switch map light/dark mode based on system color settings.

### [Set map language](https://docs.maptiler.com/sdk-js/examples/language-map/)

Tutorials

This tutorial shows how to change the default map labels language.