How can I add icons to Builder legends?

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.

Add an icon to your Legend

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

1. 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, the star marker uses 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 copy this link to the star image:

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

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

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

   For each item, a point icon will appear in the Legend by default.

3. Set the LEGEND panel toggle to HTML. Find the <p> element that contains the title of the item that you are symbolizing with an image.

   Above that you should see a <span> element similar to this:

   <span class="Legend-categoryCircle" style="opacity:1; background: #7F3C8D;"></span>
   

4. Replace that <span> 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.

1. Open your map in your CARTO dashboard and click on your layer’s card to open it.

2. 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.

3. Enter a label in the field next to the color bar in the Creating your legend section.

   Notice that you can enter field text with lower or upper case characters, but it always appears in upper case in the Legend.

4. Set the COLOR panel’s toggle to HTML. You will see a span element that looks similar to this:

   <span class="Legend-categoryCircle" style="opacity:1; background: #826DBA;"></span>
   

5. 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.

   <span style="opacity:1; border:1px solid #ffffff; background: #f1ccd0; height:8px; width:8px; display:inline-block"></span>
   

6. After changing the background color click APPLY.

Add a line to your Legend

Take the steps below to create line icons in your Legend.

1. Open your map in your CARTO dashboard and click on your layer’s card to open it.

2. 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 its color to the same one used in your STYLE panel.

3. Enter a label in the field next to the color bar in the Creating your legend section.

4. 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 <!-- and -->.

   <!-- <span class="Legend-categoryCircle" style="opacity:1; background: #4cc8a3;"></span> -->
   

5. Beneath the commented-out span element paste the code below.

   This creates a 25px wide rectangle with a bottom border that is 3px tall. This represents the line icon.

   <span style="opacity:1; border-bottom:3px solid #4cc8a3; background:#FFF; height:1px; width:25px; display:inline-block"></span>
   

6. The color of your 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. In the span element you just added beneath it, paste the color code into the border-bottom hex # value.

7. For dashed lines, paste the code below and click APPLY.

   <span style="opacity:1; border-bottom:3px dashed #1d6996; background:#FFF; height:1px; width:25px; display:inline-block"></span>
   

   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 as the icon example above.