Simple and familiar

Using colourInput is extremely trivial if you’ve used Shiny, and it’s as easy to use as any other input control. It was implemented to very closely mimic all other Shiny inputs so that using it will feel very familiar. You can add a simple colour input to your Shiny app with colourInput("col", "Select colour", value = "red"). The return value from a colourInput is an uppercase HEX colour, so in the previous example the value of input$col would be #FF0000 (#FF0000 is the HEX value of the colour red). The default value at initialization is white (#FFFFFF).

Retrieving the colour names

If you use the returnName = TRUE parameter, then the return value will be a colour name instead of a HEX value, when possible. For example, if the chosen colour is red, the return value will be red instead of #FF0000. For any colour that does not have a standard name, its HEX value will be returned.

Allowing transparent colours

A simple colour input allows you to choose any opaque colour. If you use the allowTransparent = TRUE parameter, the input will display an additional slider that lets you choose a transparency (alpha) value. Using this slider allows you to select semi-transparent colours, or even the fully transparent colour, which is sometimes useful.

When using transparent colours, the return value will be an 8-digit HEX code instead of 6 digits (the last 2 digits are the transparency value). For example, if you select a 50% transparent red, the return value would be #FF000080. Most R plotting functions can accept colours in this format.

Limited colour selection

If you want to only allow the user to select a colour from a specific list of colours, rather than any possible colour, you can use the palette = "limited" parameter. By default, the limited palette will contain 40 common colours, but you can supply your own list of colours using the allowedCols parameter. Here is an image of the default limited colour palette.

colourInput demo

Flexible colour specification

Specifying a colour to the colour input is very flexible to allow for easier use. When providing a colour as the value parameter of the input, there are a few ways to specify a colour:

• Using a name of an R colour, such as red, gold, blue3, or any other name that R supports (for a full list of R colours, type colours())
• Using a 6-character HEX value, either with or without the leading #. For example, initializing a colourInput with any of the following values will all result in the colour red: ff0000, FF0000, #ff0000. If transparency is allowed, you can use an 8-character HEX value.
• Using a 3-character HEX value, either with or without the leading #. These values will be converted to full HEX values by automatically doubling every character. For example, all the following values would result in the same colour: 1ac, #1Ac, 11aacc. If transparency is allowed, you can use a 4-character HEX value.
• Using RGB specification, such as rgb(0, 0, 255). If transparency is allowed, you can use an rgba() specification.
• Using HSL specification, such as hsl(240, 100, 50). If transparency is allowed, you can use an hsla() specification.

Protip: You can also type in any of these values directly into the input box to select that colour, instead of selecting it from the colour palette with your mouse. For example, you can click on the colour input and literally type the word “blue”, and the colour blue will get selected.

How the chosen colour is shown inside the input box

By default, the colour input’s background will match the selected colour and the text inside the input field will be the colour’s HEX value. If that’s too much for you, you can customize the input with the showColour parameter to either only show the text or only show the background colour.

Here is what a colour input with each of the possible values for showColour looks like

showColour demo

Updating a colourInput

As with all other Shiny inputs, colourInput can be updated with the updateColourInput function. Any parameter that can be used in colourInput can be used in updateColourInput. This means that you can start with a basic colour input such as colourInput("col", "Select colour") and completely redesign it with

updateColourInput(session, "col", label = "COLOUR:", value = "orange",
  showColour = "background", allowTransparent = TRUE)

Works on any device

If you’re worried that maybe someone viewing your Shiny app on a phone won’t be able to use this input properly - don’t you worry. I haven’t quite checked every single device out there, but I did spend extra time making sure the colour selection JavaScript works in most devices I could think of. colourInput will work fine in Shiny apps that are viewed on Android cell phones, iPhones, iPads, and even Internet Explorer 8+.

Features of ‘plotHelper()’

Addin vs gadget

The Plot Colour Helper is available as both a gadget and an RStudio addin. This means that it can be invoked in one of two ways:

• Highlight code for a plot and select the addin through the Addins menu, or
• Call the plotHelper(code) function with plot code as the first parameter.

There is a small difference between the two: invoking the addin via plotHelper() will merely return the final colour list as a vector, while using the Addins menu will result in the entire plot code and colour list getting inserted into the document.

Most important to understand: Use CPCOLS in your plot code

The Plot Colour Helper lets you run code for a plot, and select a list of colours. But how does the list of colours get linked to the plot? The colour list is available as a variable called CPCOLS. This means that in order to refer to the colour list, you need to use that variable in your plot code. You can even refer to it more than once if you want to select colours for multiple purposes in the plot:

plotHelper(ggplot(iris, aes(Sepal.Length, Petal.Length)) +
    geom_point(aes(col = Species)) +
    scale_colour_manual(values = CPCOLS[1:3]) +
    theme(panel.background = element_rect(CPCOLS[4])),
    colours = 4)

Default plot if no code is provided

To more easily access the tool, you can call plotHelper() with no parameters or select the addin without highlighting any code. In that case, the default code in the tool will be initialized as

ggplot(iris, aes(Sepal.Length, Petal.Length)) +
      geom_point(aes(col = Species)) +
      scale_colour_manual(values = CPCOLS)

You can always change the plot code from within the tool.

Initial list of colours

You can set the initial colour list by providing a vector of colours as the colours parameter to plotHelper() (eg. plotHelper(colours = c("red", "#123ABC"))).

Alternatively, if you don’t want to initialize to any particular set of colours, but you want to initialize with a specific number of colours in the list, you can provide an integer as the colours parameter (eg. plotHelper(colours = 2)).

If the colour values are not provided, then a default palette of colours will be used for the initial colours. This palette has 12 colours, and if there are more than 12 colours to support then they will get recycled.

Plot Colour Helper tries to guess how many colours are needed

If you don’t provide the colours parameter, or if you invoke the tool as an addin, it will attempt to guess how many colours are needed. For example, using the following plot code

ggplot(mtcars, aes(wt, mpg)) +
    geom_point(aes(col = as.factor(am))) +
    scale_colour_manual(values = CPCOLS)

will initialize the tool with 2 colours (because there are 2 am levels), while the following code

ggplot(mtcars, aes(wt, mpg)) +
    geom_point(aes(col = as.factor(cyl))) +
    scale_colour_manual(values = CPCOLS)

will use 3 colours.

Keyboard shortcuts

There are several keyboard shortcuts available, to make the selection process even simpler. Spacebar to add another colour, Delete to remove the currently selected colour, Left/Right to navigate the colours, and more. You can view the full list of shortcuts by clicking on Show keyboard shortcuts.

Return value of Plot Colour Helper

When the tool is run as an addin, the final colour list and the code get inserted into the currently selected RStudio document (either the Source panel or the Console panel).

If the tool is called with plotHelper(), then the return value is simply the vector of selected colours. You can assign it into a variable directly - running cols <- plotHelper() will assign the selected colours into cols.

Since the plot code requires you to use the variable name CPCOLS, after closing the plot helper tool, a variable named CPCOLS will be available in the global environment.

The colours returned can either be in HEX format (eg. “#0000FF”) or be named (eg. “blue”) - you can choose this option inside the tool.