Skip to main content

Legends

Numerical scale legends

Specification

To render the legend of a numerical color scale, you can use the drawLegend function as follow:

smplr.Color.drawLegend({
  containerId: string
  colorScale: (n: number | null | undefined) => string
  domain?: [number, number]
  ticks?: Record<number, number | string>
  barStyle?: CSSProperties
  labelStyle?: CSSProperties
  correctColor?: boolean
})
  • containerId is the "id" of the html container where smplr.js should render the legend, something like "smplr-legend" that can be found in your html. Only ids are supported, not classes.
  • colorScale is the numerical color scale for which the legend is rendered. It can come from our numericScale, or be a custom function that takes a numerical value and returns a color string.
  • domain - optional - is the range of values to render the scale for. Default value: [0,1].
  • ticks - optional - are the values to label at the bottom of the legend. It is defined as an object where the keys are the numerical values where the tick should be and the value are the labels. By default, there is one tick at each end of the legend with the numerical value displayed without formatting.
  • barStyle - optional - react style object that will be applied to the bar containing the colors.
  • labelStyle - optional - react style object that will be applied to the container of the labels. It is merged with ours: { fontSize: '0.8em', opacity: 0.5, height: 18 }. We set the height manually as the labels are absolutely positioned. You may need to change the height if you change the font or its size.
  • correctColor - optional - lets you choose if the colors of the legend should be corrected to match the ones from the viewer as per the explanation in the color mapping section. We correct them by default. Default value: true.

Note that the Legend will fill the width of its container.

Example

Loading...

was rendered with the code below:

smplr.Color.drawLegend({
  containerId: "legend",
  colorScale: smplr.Color.numericScale({
    name: smplr.Color.NumericScale.RdYlBu,
    domain: [10, 30],
    invert: true,
  }),
  domain: [10, 30],
  ticks: {
    10: "10°C",
    20: "20°C",
    30: "30°C",
  },
});

Categorical scale legends

Specification

To render the legend of a categorical color scale, you can use the drawColorSwatches function as follow:

smplr.Color.drawColorSwatches({
  containerId: string
  swatches: {
    color: string
    label: string
    group?: string
  }[]
  size?: number
  correctColor?: boolean
  noLabels?: boolean
})
  • containerId is the "id" of the html container where smplr.js should render the legend, something like "smplr-legend" that can be found in your html. Only ids are supported, not classes.
  • swatches defines the colors and labels used for the swatches. Note that an optional group can be provided to create multiple lines with a label ahead of each group. You can refer to the ragSwatches and categorySwatches helpers to generate swatches for categorical scales generated with our functions.
  • size - optional - is the size in pixels of each swatch. Default value: 10.
  • correctColor - optional - lets you choose if the colors of the legend should be corrected to match the ones from the viewer as per the explanation in the color mapping section. We correct them by default. Default value: true.
  • noLabels - optional - set this to true to hide labels. Default value: false.

Example

Loading...

was rendered with the code below:

smplr.Color.drawColorSwatches({
  containerId: 'smplr-legend',
  swatches: [
    {
      color: 'red',
      label: 'Alert',
    },
    {
      color: 'orange',
      label: 'Warning',
    },
    {
      color: 'green',
      label: 'All ok',
    },
  ]
});

Icons legends

Specification

To render the legend for icons, you can use the drawIconsSwatches function as follow:

smplr.Color.drawIconsSwatches({
  containerId: string
  icons: {
    url: string
    label: string
    group?: string
  }[]
  height?: number
  noLabels?: boolean
})
  • containerId is the "id" of the html container where smplr.js should render the legend, something like "smplr-legend" that can be found in your html. Only ids are supported, not classes.
  • icons defines the icons and labels used for the swatches. Note that an optional group can be provided to create multiple lines with a label ahead of each group.
  • height - optional - is the height in pixels of each swatch. Default value: 16.
  • noLabels - optional - set this to true to hide labels. Default value: false.

Example

Loading...

was rendered with the code below:

smplr.Color.drawIconsSwatches({
  containerId: 'smplr-legend',
  icons: [
    {
      url: 'https://retail.smplrspace.io/img/electric.png',
      label: 'EV charging',
    },
    {
      url: 'https://retail.smplrspace.io/img/wheelchair.png',
      label: 'Reduced mobility',
    }
  ],
  height: 20
});