Hey! This content applies only to previous CARTO products

Please check if it's relevant to your use case. On October 2021 we released a new version of our platform.
You can learn more and read the latest documentation at docs.carto.com

Questions / Building Maps / Builder

How can I add icons to Builder legends?

Learn how to match Legend symbols to map feature symbols.

CARTO Builder gives you the ability to symbolize point features with images. As a “best practice” to ensure legibility, you should make your Legend symbols match your point marker icons. This can be done in Builder with custom HTML. You can also represent line features with a Legend line, and polygon features with a Legend square.

In this map we are using circle markers to represent cities, except for a star icon that represents the state capital. We are also using polygon geometry to represent census tracts, and line geometry to represent roads and ferry routes.

Kodiak Alaska Map with custom legend

Add an icon to your Legend

You can use the same image for your point marker style and your Legend.

After you finish styling your point markers with images, make sure your STYLE panel toggle is set to CARTOCSS. Copy the url you find inside quotes in the marker-file definition.

For example, our star marker is in this CartoCSS style rule:

 marker-file: ramp([name], (url("https://s3.amazonaws.com/com.cartodb.users-assets.production/production/documentation/assets/20190513213949star.svg")), ("Juneau"), "=");

From there we copied this link to the star image:

 https://s3.amazonaws.com/com.cartodb.users-assets.production/production/documentation/assets/20190513213949star.svg

Click on the layer’s LEGEND panel. Select the CUSTOM thumbnail in the Select Style section of the COLOR panel.

Notice that the Legend items auto-populate based on your current styles. If you are using custom CartoCSS and the Legend items don’t auto-populate, you can click ADD ITEM and select the appropriate colors.

For each item, a point icon will appear in the Legend by default.
Set the LEGEND panel toggle to HTML. Find the  element that contains the title of the item that you are symbolizing with an image.

Above that you should see a  element similar to this:
```
 
```

Replace that  element with the line below.

 <span style="opacity:1; height:15px; width:15px; background-image: url('https://s3.amazonaws.com/com.cartodb.users-assets.production/production/documentation/assets/20190513213949star.svg') no-repeat center; background-size: 15px 15px;"></span>

Replace the src url with the one you copied from your marker-file style and click APPLY.

You can also change the pixel sizes as needed to accommodate your icon’s dimensions.

Add a square to your Legend

Take the steps below to create a square icon in your Legend, like we did for CENSUS TRACTS in the map above.

Open your map in your CARTO dashboard and click on your layer’s card to open it.
Click on your map layer’s LEGEND tab and select the CUSTOM thumbnail in the Select Style section of the COLOR panel. Notice that a point icon appears in the Legend by default.
Enter a label in the field next to the color bar in the Creating your legend section. We entered census tracts in the example map above.

Notice that you can enter field text with lower or upper case characters, but it always appears in upper case in the Legend.
Set the COLOR panel’s toggle to HTML. You will see a span element that looks similar to this:
```
 
```
Replace that span element with the one below. It adds an 8 pixel by 8 pixel square to the legend and gives it a white outline to match the Legend’s white background.

Change the background color to the same one you’re using for your map feature. You can copy the feature’s hex color code from the color picker HEX value, which is visible when you click on the layer STYLE panel’s POLYGON COLOR color bar.
```
 
```
After changing the background color click APPLY.

Add a line to your Legend

Take the steps below to create line icons in your Legend, like we did for ROAD and FERRY in the map above.

Open your map in your CARTO dashboard and click on your layer’s card to open it.
Click on your map layer’s LEGEND tab and select the CUSTOM thumbnail in the Select Style section of the COLOR panel.

In the LEGEND panel’s Creating your legend section you should make sure an item has been added for each of the different symbols used in your layer. Click on the color bar for each item and set it’s color to the same one used in your STYLE panel.
Enter a label in the field next to the color bar in the Creating your legend section. We used road for the first label and ferry for the second.
Set the COLOR panel’s toggle to HTML. You will see a span element for each of your items.

Comment them out by enclosing each span element in a .
```
 
```
Beneath the commented-out span element for road paste the code below.

This creates a 25px wide rectangle with a bottom border that is 3px tall. This represents our line icon.
```
 
```
The color of our line icon is controlled by the border-bottom color property. The commented-out span elements already include the background colors needed for your lines.

Copy the background hex color from the span element commented out for road. In the span element you just added beneath it, paste the color code into the border-bottom hex # value.
For ferry routes, we used line-dasharray styling to create a dashed line. We can create a dashed line icon in our Legend also.

Beneath the commented-out span element for ferry paste the code below and click APPLY.
```
 
```
To match the map feature’s line dash pattern exactly and consistently across browsers you can use a dashed image in the Legend. It would be implemented the same way we did above for Juneau’s Legend symbol.