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

- [Use a color scale offered by Studio](https://docs.foursquare.com/developer/docs/studio-map-sdk-legend-config#use-a-studio-color-scale)
- [Create a custom color scale](https://docs.foursquare.com/developer/docs/studio-map-sdk-legend-config#create-custom-color-scale)
- [Edit text describing colors on the legend](https://docs.foursquare.com/developer/docs/studio-map-sdk-legend-config#edit-legend-text)

To control the color scale for raster tiles, [please see the schema parts within `config.visConfig`](https://docs.foursquare.com/developer/docs/studio-layer-reference#raster-tile).

### 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 value | Description |
| --- | --- |
| `"quantize"` | [Quantize](https://docs.foursquare.com/studio/docs/layers-color-scale-and-palettes#quantize-equal-interval) divides the range of the continuous variable into equal interval bins. |
| `"quantile"` | [Quantile](https://docs.foursquare.com/studio/docs/layers-color-scale-and-palettes#quantile) organizes the data values by grouping them into bins that each have the same number of data values. |
| `"jenks"` | [Jenks Natural Breaks](https://docs.foursquare.com/studio/docs/layers-color-scale-and-palettes#jenks-natural-breaks) arranges the data values into different groups where the within-group homogeneity is maximized |
| `"custom"` | A [custom color scale](https://docs.foursquare.com/studio/docs/layers-color-scale-and-palettes#custom-breaks). Requires modification of `config.visConfig.colorRange`. |

The updated layer configuration JSON file can be passed via the [`updateLayer` function](https://docs.foursquare.com/developer/docs/studio-map-sdk-layer-functions#update-layer).

## Sample `colorScale`: Studio Color Scale  
In this example, `"colorScale"` is set to `"jenks"`.

```json
"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`](https://docs.foursquare.com/developer/docs/studio-layer-reference#configvisconfigcolorrange).

Fields used in the `colorRange` object:

| `colorRange` Field | Type | Description |
| --- | --- | --- |
| `"name"` | `string` | The name of the color range. For a custom color range, must be `"color.customPalette"`. |
| `"type"` | `string` | The type of color range to use. For a custom color range, must be `"custom"`. |
| `"category"` | `string` | The category of the color range. For a custom color range, must be `"Custom"`. |
| `"colors"` | `string array` | A list of colors to use, described by their 6-digit hex values. Only use colors to be used in `"colorMap"`. |
| `colorMap` | `map` | A 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. |

## 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"`.

```json
 "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:

```json
"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](https://docs.foursquare.com/developer/docs/studio-layer-reference#point).

```json
"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
}
```