SDK Docs
Support

Legend and Color Scale Configuration via SDK

Suggest Edits

This page contains guidance for programmatically editing the legend, including how to:

To control the color scale for raster tiles, please see the schema parts within config.visConfig.

🚧

Note: Pinning the legend is currently not accessible programmatically and can only be accomplished from Studio's user interface.

Use a Studio Color Scale

To use a color scale offered by Studio, edit the string in a supported layer's config.visualChannels.colorScale. Some layers also support color scales for other layer components, such as strokes on the point layer (see strokeColorScale in the below example).

Set the color scale to one of the following string values:

colorScale string valueDescription
"quantize"Quantize divides the range of the continuous variable into equal interval bins.
"quantile"Quantile organizes the data values by grouping them into bins that each have the same number of data values.
"jenks"Jenks Natural Breaks arranges the data values into different groups where the within-group homogeneity is maximized
"custom"A custom color scale. Requires modification of config.visConfig.colorRange. See the section below.

The updated layer configuration JSON file can be passed via the updateLayer function.

Sample colorScale: Studio Color Scale

In this example, "colorScale" is set to "jenks".

"visualChannels": {
    "colorField": {
        "name": "popularity",
        "type": "real"
    },
    "colorScale": "jenks",
    "strokeColorField": null,
    "strokeColorScale": "quantile",
    "sizeField": {
        "name": "popularity",
        "type": "real"
    },
    "sizeScale": "sqrt"
}

Create Custom Color Scale

The layer's color scale configuration can be found in a supported layer's config.visConfig.colorRange.

Fields used in the colorRange object:

colorRange FieldTypeDescription
"name"stringThe name of the color range. For a custom color range, must be "color.customPalette".
"type"stringThe type of color range to use. For a custom color range, must be "custom".
"category"stringThe category of the color range. For a custom color range, must be "Custom".
"colors"string arrayA list of colors to use, described by their 6-digit hex values. Only use colors to be used in "colorMap"
colorMapmapA map of values to colors. All colors used should be provided in the "colors" array. A single entry on the map describes the color range less than the value provided. The first color will be applied to values smaller than the float provided. The last color should map to null, and will be applied to all values larger than the previous value. See the example below.

The updated layer configuration JSON file can be passed via the updateLayer function.

Sample colorRange: Custom Color Scale

In this example, six colors are defined in a "colors" array, then are mapped to a range of values in "colorMap".

 "colorRange": {
    "name": "color.customPalette",
    "type": "custom",
    "category": "Custom",
    "colors": [
        "#4C0035",
        "#880030",
        "#B72F15",
        "#D6610A",
        "#EF9100",
        "#FFC300"
    ],
    "colorMap": [
        [2, "#4C0035"],
        [3, "#880030"],
        [4, "#B72F15"],
        [5, "#D6610A"],
        [6, "#EF9100"],
        [null, "#FFC300"]
    ]
}

Edit Legend Text

Text appearing on the legend can be updated by mapping a new string to an existing color value in visConfig.colorRange.colorLegends. The colorLegends object should be formatted similarly to the following example:

"colorLegends": {
    "#4C0035": "Custom",
    "#880030": "Legend",
    "#B72F15": "Text",
    "#D6610A": "Example",
    "#EF9100": "Config",
    "#FFC300": "File"
}

The legend text can be reset to display the default values by removing the "colorLegends" object.

visConfig with Custom Color Scale and Legend

The following is a visConfig from a point layer's JSON config.

"visConfig": {
    "radius": 10,
    "fixedRadius": false,
    "opacity": 1,
    "outline": false,
    "thickness": 2,
    "strokeColor": null,
    "colorRange": {
        "name": "color.customPalette",
        "type": "custom",
        "category": "Custom",
        "colors": [
            "#4C0035",
            "#880030",
            "#B72F15",
            "#D6610A",
            "#EF9100",
            "#FFC300"
        ],
        "colorMap": [
            [0.15, "#4C0035"],
            [0.25, "#880030"],
            [0.35, "#B72F15"],
            [0.45, "#D6610A"],
            [0.55, "#EF9100"],
            [null, "#FFC300"]
        ],
        "colorLegends": {
            "#4C0035": "Custom",
            "#880030": "Legend",
            "#B72F15": "Text",
            "#D6610A": "Example",
            "#EF9100": "Config",
            "#FFC300": "File"
        }
    },
    "filled": true,
    "billboard": false,
    "allowHover": false,
    "showNeighborOnHover": false,
    "showHighlightColor": true
}

Updated 11 months ago