Legend Configuration

Define map legends alongside your config using legend_config to render visual keys that stay in sync with your parameters.

How it works

The legend_config object sits alongside config and params_config in your JSON. It specifies a legend type and an array of items. Legend item values can use @@#params references, keeping the legend in sync with your parameter controls.

Structure

legend_config shape
{
  "legend_config": {
    "type": "basic | choropleth | gradient",
    "items": [
      {
        "label": "Category A",
        "value": "#dc2626"
      },
      {
        "label": "Category B",
        "value": "#3b82f6"
      }
    ]
  }
}

Legend types

Basic

Simple color swatches with labels. Best for categorical data.

Forest
Water
Urban

Choropleth

Color ramps with boundary labels. Best for classified/binned data.

LowMediumHigh

Gradient

Continuous color gradient. Best for interpolated/continuous data.

LowHigh

Parameterized legends

Legend item values can reference parameters. When a param has group: 'legend', its control appears inside the legend card, keeping color selection and legend display in sync.

Parameterized basic legend
Change the category colors and see the legend update.
Input
{
  "legend_config": {
    "type": "basic",
    "items": [
      {
        "label": "Forest",
        "value": "@@#params.forest_color"
      },
      {
        "label": "Water",
        "value": "@@#params.water_color"
      },
      {
        "label": "Urban",
        "value": "@@#params.urban_color"
      }
    ]
  }
}
Controls
Output
{
  "legend_config": {
    "type": "basic",
    "items": [
      {
        "label": "Forest",
        "value": "#22c55e"
      },
      {
        "label": "Water",
        "value": "#3b82f6"
      },
      {
        "label": "Urban",
        "value": "#94a3b8"
      }
    ]
  }
}
Legend preview
Forest
Water
Urban
Parameterized choropleth legend
Change the colors and see both the config output and legend update.
Input
{
  "legend_config": {
    "type": "choropleth",
    "items": [
      {
        "label": "Sparse",
        "value": "@@#params.low_color"
      },
      {
        "label": "Medium",
        "value": "@@#params.mid_color"
      },
      {
        "label": "Dense",
        "value": "@@#params.high_color"
      }
    ]
  }
}
Controls
Output
{
  "legend_config": {
    "type": "choropleth",
    "items": [
      {
        "label": "Sparse",
        "value": "#dbeafe"
      },
      {
        "label": "Medium",
        "value": "#3b82f6"
      },
      {
        "label": "Dense",
        "value": "#1e3a5f"
      }
    ]
  }
}
Legend preview
SparseMediumDense
Parameterized gradient legend
Adjust the gradient stops and watch the legend update in real time.
Input
{
  "legend_config": {
    "type": "gradient",
    "items": [
      {
        "label": "Cold",
        "value": "@@#params.cold_color"
      },
      {
        "label": "Warm",
        "value": "@@#params.warm_color"
      },
      {
        "label": "Hot",
        "value": "@@#params.hot_color"
      }
    ]
  }
}
Controls
Output
{
  "legend_config": {
    "type": "gradient",
    "items": [
      {
        "label": "Cold",
        "value": "#440154"
      },
      {
        "label": "Warm",
        "value": "#21918c"
      },
      {
        "label": "Hot",
        "value": "#fde725"
      }
    ]
  }
}
Legend preview
ColdWarmHot