Style a feature layer | MapLibre GL JS

Learn how to use style a feature layer.

Style a feature layer using API key authentication

A feature layer is a dataset in a feature service hosted in an ArcGIS portal. Each feature layer contains features with a single geometry type (point, line, or polygon), and a set of attributes. A feature layer can be styled in MapLibre GL JS with a layer connected to a GeoJSON source.

In this tutorial, you use symbol, line, and fill layers to style three hosted feature layers using the MapLibre ArcGIS plugin.

Prerequisites

You need an ArcGIS Location Platform or ArcGIS Online account.

Steps

Get the starter app

Select a type of authentication and follow the steps to create a new app.

Choose API key authentication if you:

Want the easiest way to get started.
Want to build public applications that access ArcGIS Location Services and secure items.
Have an ArcGIS Location Platform or ArcGIS Online account.

Choose user authentication if you:

Want to build private applications.
Require application users to sign in with their own ArcGIS account and access resources their behalf.
Have an ArcGIS Online account.

To learn more about both types of authentication, go to Authentication.

You can choose one of the following to create a new CodePen:

Option 1: Complete the Display a map tutorial; or,
Option 2: Start from the Display a map tutorial .

Set up authentication

Create a new API key credential with the correct privileges to get an access token.

Go to the Create an API key tutorial to follow the steps to get an access token with these privilege(s):
- Privileges
  - Location services > Basemaps
- Item access
  - Note: If you are using your own custom data layer for this tutorial, you need to grant the API key credentials access to the layer item. Learn more in Item access privileges.

Set developer credentials

Use the API key or OAuth developer credentials so your application can access ArcGIS services.

Update the accessToken variable to use your API key.

Expand
Use dark colors for code blocks
 /* Use for API key authentication */  const accessToken = "YOUR_ACCESS_TOKEN"; 
Expand

In both the index.html and callback.html files, replace YOUR_CLIENT_ID and YOUR_REDIRECT_URL with the client ID and redirect URL of your OAuth credentials.

index.html
Use dark colors for code blocks
 /* Use for user authentication */  const clientId = "YOUR_CLIENT_ID"; // Your client ID from OAuth credentials  const redirectUri = ""YOUR_REDIRECT_URI""; // The redirect URL registered in your OAuth credentials  const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({  clientId,  redirectUri,  portal: "https://www.arcgis.com/sharing/rest" // Your portal URL  });   const accessToken = session.token; 

callback.html
Use dark colors for code blocks
 arcgisRest.ArcGISIdentityManager.completeOAuth2({  clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials  redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials  portal: "https://www.arcgis.com/sharing/rest" // Your portal URL  }); 

Run the app and ensure you can sign in successfully.

If you are unable to sign in, make sure you have the correct redirect URL and port. This URL varies based on your application and typically takes the format of https://<server>[:port]/callback.html or http://my-arcgis-app:/auth. For example, if you are running an application on http://127.0.0.1:5500/, set http://127.0.0.1:5500/callback.html as your redirect URL in the index.html and callback.html file and your developer credential. They all have to match!

Load a hiker icon

To use an image as an icon, you must first load the image into the map style using map.loadImage and map.addImage.

Call map.loadImage with 'https://static.arcgis.com/images/Symbols/NPS/npsPictograph_0231b.png' as the first parameter. The second parameter is a callback taking an error and the image.

See the MapLibre GL JS documentation for more information.

Expand
Use dark colors for code blocks
 const map = new maplibregl.Map({  container: "map", // the id of the div element  zoom: 12, // starting zoom  center: [-118.805, 34.027] // starting location [longitude, latitude]  });  const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, {  style: "arcgis/outdoor",  token: accessToken  });   map.loadImage("https://static.arcgis.com/images/Symbols/NPS/npsPictograph_0231b.png").then((resp) => {   }); 
Expand

Call map.addImage to define hiker-icon as the provided image.

A MapLibre style can contain a number of images as part of its sprite file. map.addImage is required to display images that are not included in its sprite file.

See the MapLibre GL JS documentation for more information.

Expand
Use dark colors for code blocks
 map.loadImage("https://static.arcgis.com/images/Symbols/NPS/npsPictograph_0231b.png").then((resp) => {   map.addImage("hiker-icon", resp.data);   }); 
Expand

Style and display trailheads with a hiker icon and labels

To display an icon of a hiker for each trailhead, along with a label, you can use a single symbol layer. Properties for the label start with text- and properties for the icon start with icon-.

Create an asynchronous function called showTrailheads. Inside, use the plugin to create a new FeatureLayer object that references the Trailheads feature service, then add the sources to the map.

Expand
Use dark colors for code blocks
 map.loadImage("https://static.arcgis.com/images/Symbols/NPS/npsPictograph_0231b.png").then((resp) => {   map.addImage("hiker-icon", resp.data);   });   async function showTrailheads() {   const trailheads = await maplibreArcGIS.FeatureLayer.fromUrl("https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0");  trailheads.addSourcesTo(map);   });  } 
Expand

Add a symbol layer for the hiker icons. Use icon-image to reference the icon you loaded.

Expand
Use dark colors for code blocks
 async function showTrailheads() {   const trailheads = await maplibreArcGIS.FeatureLayer.fromUrl("https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0");  trailheads.addSourcesTo(map);   map.addLayer({  ...trailheads.layer,  type: "symbol",  layout: {  "icon-image": "hiker-icon",  "icon-size": 0.3,  "icon-allow-overlap": true,   }   });  } 
Expand

Add additional label properties. Set a text-anchor of bottom, with a text-offset of [0, -2] to position the label above the icon. Use the TRL_NAME attribute as the text field.

Expand
Use dark colors for code blocks
 map.addLayer({  ...trailheads.layer,  type: "symbol",  layout: {  "icon-image": "hiker-icon",  "icon-size": 0.3,  "icon-allow-overlap": true,   "text-font": ["Arial Italic"],  "text-field": ["get", "TRL_NAME"],  "text-size": 12,  "text-anchor": "bottom",  "text-offset": [0, -2]   },  paint: {  "text-color": "white",  "text-halo-color": "seagreen",  "text-halo-width": 2   } 
Expand

Add a load event handler

It is important to wait for the MapLibre GL JS map to finish loading before adding any layers.

Add an event handler to the map load event. Inside, call the showTrailheads function.

Expand
Use dark colors for code blocks
 },  paint: {  "text-color": "white",  "text-halo-color": "seagreen",  "text-halo-width": 2   }   });  }   map.on("load", async () => {   await showTrailheads();   }); 
Expand

Style and display all trails

Create an asynchronous function called showTrails. Inside, use the plugin to create a new FeatureLayer object that references Trails feature service, then add the sources to the map.

Expand
Use dark colors for code blocks
 },  paint: {  "text-color": "white",  "text-halo-color": "seagreen",  "text-halo-width": 2   }   });  }   async function showTrails() {   const trails = await maplibreArcGIS.FeatureLayer.fromUrl("https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trails/FeatureServer/0");  trails.addSourcesTo(map);  
Expand

Add a line layer with id trails-line to display the trails source.

Expand
Use dark colors for code blocks
 async function showTrails() {   const trails = await maplibreArcGIS.FeatureLayer.fromUrl("https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trails/FeatureServer/0");  trails.addSourcesTo(map);   map.addLayer({  ...trails.layer,  paint: {  "line-color": "hsl(291, 44%, 60%)",   "line-opacity": 0.75  }  });  
Expand

To show trails that allow bikes with a dashed line, create a new layer that sits above the other layer. You can reuse the existing source with a different id of biketrails-line. Use a filter to only show trails where USE_BIKE has a value of YES. Set line-dasharray to [1, 2] to create short dashes.

Expand
Use dark colors for code blocks
 map.addLayer({  ...trails.layer,  paint: {  "line-color": "hsl(291, 44%, 60%)",   "line-width": ["interpolate", ["linear"], ["get", "ELEV_GAIN"], 0, 3, 2300, 7],   "line-opacity": 0.75  }  });   map.addLayer({  ...trails.layer,  id: "bike-trails",  filter: ["==", ["get", "USE_BIKE"], "Yes"],  paint: {  "line-dasharray": [1, 2],  "line-width": 2,  "line-color": "hsl(300, 100%, 78.4%)"  }  });   } 
Expand

Style trail width by elevation gain

To make the width of the trail line reflect the elevation gain, you can use a MapLibre GL expression as the value of the line-width. You use the ['interpolate'] and ['get'] expressions to achieve this.

['interpolate', ['linear'], ... creates a linear mapping from one range of input values (the number of feet of elevation gain) to a range of output values (the number of pixels of line width). You provide "stops", such as mapping 2,300 feet to 7 pixels. See the MapLibre Style Specification for details.

['get', 'ELEV_GAIN'] accesses the ELEV_GAIN property. See the MapLibre Style Specification for details.

Update the trails-line layer definition that calculates line-width from the ELEV_GAIN attribute.

Expand
Use dark colors for code blocks
 map.addLayer({  ...trails.layer,  paint: {  "line-color": "hsl(291, 44%, 60%)",   "line-width": ["interpolate", ["linear"], ["get", "ELEV_GAIN"], 0, 3, 2300, 7],   "line-opacity": 0.75  }  }); 
Expand

Display park areas with different colors

You can use a different style for each unique attribute value in a feature layer. Use a ['match', ...] expression to display park polygons with different colors depending on the TYPE field.

A ['match', ...] expression choose between several different output values depending on the input value. See the MapLibre Style Specification for details.

Create an asynchronous function called showParks. Inside, use the plugin to create a new FeatureLayer object that references the Parks feature service, then add the sources to the map.

Expand
Use dark colors for code blocks
 map.addLayer({  ...trails.layer,  id: "bike-trails",  filter: ["==", ["get", "USE_BIKE"], "Yes"],  paint: {  "line-dasharray": [1, 2],  "line-width": 2,  "line-color": "hsl(300, 100%, 78.4%)"  }  });   }   async function showParks() {   const parks = await maplibreArcGIS.FeatureLayer.fromUrl("https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Parks_and_Open_Space/FeatureServer/0");  parks.addSourcesTo(map);   } 
Expand

Add a fill layer with id parks-fill and source parks. For the fill color, use a match expression for different TYPE values.

Expand
Use dark colors for code blocks
 async function showParks() {   const parks = await maplibreArcGIS.FeatureLayer.fromUrl("https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Parks_and_Open_Space/FeatureServer/0");  parks.addSourcesTo(map);   map.addLayer({  ...parks.layer, // The layer property contains a preformatted maplibre layer, including a layer ID and source.  paint: { // Override default paint properties provided by parks.layer  "fill-color": [  "match", ["get", "TYPE"],  "Natural Areas", "#9E559C",  "Regional Open Space", "#A7C636",  "Local Park", "#149ECE",  "Regional Recreation Park", "#ED5151",  "black"  ],  "fill-opacity": 0.2  }  });   } 
Expand

Back inside the load event handler, call the showParks functions. Place it before the other functions so that the parks layer is placed under the trails and trailheads.

Expand
Use dark colors for code blocks
 map.on("load", async () => {   await showParks();   await showTrails();   await showTrailheads();   }); 
Expand

Run the app

Run the app.

You should now see trailheads with icons and labels, trails whose width varies by elevation, dashed lines for trails that allow bikes, and parks of different colors.

What's next?

Learn how to use additional location services in these tutorials:

Style vector tiles

Change the fill and outline color of vector tiles based on their attributes on the client side.

Search for an address

Find an address or place using a search box.

Find a route and directions

Find a route and directions from a start and finish location.