Skip to content

Conveniently maps data values (numeric or factor/character) to colors according to a given palette, which can be provided in a variety of formats.


  na.color = "#808080",
  alpha = FALSE,
  reverse = FALSE

  bins = 7,
  pretty = TRUE,
  na.color = "#808080",
  alpha = FALSE,
  reverse = FALSE,
  right = FALSE

  n = 4,
  probs = seq(0, 1, length.out = n + 1),
  na.color = "#808080",
  alpha = FALSE,
  reverse = FALSE,
  right = FALSE

  levels = NULL,
  ordered = FALSE,
  na.color = "#808080",
  alpha = FALSE,
  reverse = FALSE



The colors or color function that values will be mapped to


The possible values that can be mapped.

For colorNumeric and colorBin, this can be a simple numeric range (e.g. c(0, 100)); colorQuantile needs representative numeric data; and colorFactor needs categorical data.

If NULL, then whenever the resulting color function is called, the x value will represent the domain. This implies that if the function is invoked multiple times, the encoding between values and colors may not be consistent; if consistency is needed, you must provide a non-NULL domain.


The color to return for NA values. Note that na.color = NA is valid.


Whether alpha channels should be respected or ignored. If TRUE then colors without explicit alpha information will be treated as fully opaque.


Whether the colors (or color function) in palette should be used in reverse order. For example, if the default order of a palette goes from blue to green, then reverse = TRUE will result in the colors going from green to blue.


Either a numeric vector of two or more unique cut points or a single number (greater than or equal to 2) giving the number of intervals into which the domain values are to be cut.


Whether to use the function pretty() to generate the bins when the argument bins is a single number. When pretty = TRUE, the actual number of bins may not be the number of bins you specified. When pretty = FALSE, seq() is used to generate the bins and the breaks may not be "pretty".


parameter supplied to cut. See Details


Number of equal-size quantiles desired. For more precise control, use the probs argument instead.


See quantile. If provided, the n argument is ignored.


An alternate way of specifying levels; if specified, domain is ignored


If TRUE and domain needs to be coerced to a factor, treat it as already in the correct order


A function that takes a single parameter x; when called with a vector of numbers (except for colorFactor, which expects factors/characters), #RRGGBB color strings are returned (unless

alpha = TRUE in which case #RRGGBBAA may also be possible).


colorNumeric is a simple linear mapping from continuous numeric data to an interpolated palette.

colorBin also maps continuous numeric data, but performs binning based on value (see the cut function). colorBin defaults for the cut function are include.lowest = TRUE and right = FALSE.

colorQuantile similarly bins numeric data, but via the quantile function.

colorFactor maps factors to colors. If the palette is discrete and has a different number of colors than the number of factors, interpolation is used.

The palette argument can be any of the following:

  1. A character vector of RGB or named colors. Examples: palette(), c("#000000", "#0000FF", "#FFFFFF"), topo.colors(10)

  2. The name of an RColorBrewer palette, e.g. "BuPu" or "Greens".

  3. The full name of a viridis palette: "viridis", "magma", "inferno", or "plasma".

  4. A function that receives a single value between 0 and 1 and returns a color. Examples: colorRamp(c("#000000", "#FFFFFF"), interpolate = "spline").


pal <- colorBin("Greens", domain = 0:100)
pal(runif(10, 60, 100))
#>  [1] "#31A354" "#31A354" "#31A354" "#31A354" "#31A354" "#31A354" "#006D2C"
#>  [8] "#31A354" "#006D2C" "#006D2C"

if (interactive()) {
  # Exponential distribution, mapped continuously
  previewColors(colorNumeric("Blues", domain = NULL), sort(rexp(16)))
  # Exponential distribution, mapped by interval
  previewColors(colorBin("Blues", domain = NULL, bins = 4), sort(rexp(16)))
  # Exponential distribution, mapped by quantile
  previewColors(colorQuantile("Blues", domain = NULL), sort(rexp(16)))

  # Categorical data; by default, the values being colored span the gamut...
  previewColors(colorFactor("RdYlBu", domain = NULL), LETTERS[1:5])
  # ...unless the data is a factor, without droplevels...
  previewColors(colorFactor("RdYlBu", domain = NULL), factor(LETTERS[1:5], levels = LETTERS))
  # ...or the domain is stated explicitly.
  previewColors(colorFactor("RdYlBu", levels = LETTERS), LETTERS[1:5])