Block colour

Most Blockly apps use a variety of block colours to visually group the blocks into categories. The blocks shipped with Blockly include eight categories, with the colours mirrored by the various toolbar categories in the demos:

A screenshot of a workspace with an example of each block color.

Many toolbox entries also include shadow blocks as default input values. For instance, the numbers of the blue addition block. The colour of a shadow block is derived from the block's standard colour, but desaturated.

Defining the block colour

The block colour can be defined in either the JSON or JavaScript notations:

JSON

{
  // ...,
  "colour": 160,
}

JavaScript

init: function() {
  // ...
  this.setColour(160);
}

Note the British spelling. Failure to set the colour results in a black block.

The colour value can take one of several forms. The simplest is a number between 0-360, defining the block's hue in the hue-saturation-value (HSV) colour model.

Using HSV with saturation and value fixed for all block colours allows you to easily select a block colour, while ensuring all blocks share a cohesive palette.

Several color pickers offer the HSV colour space, such as HSV picker. Enter Blockly's saturation and value constants (the defaults are 45% and 65% respectively), then slide the hue as desired. Use this hue number as the colour value (JSON), or the argument to the this.setColour(..) function (JavaScript).

The saturation and values can be adapted for each application by overriding the following Blockly constants:

Blockly.HSV_SATURATION // 0 (inclusive) to 1 (exclusive), defaulting to 0.45
Blockly.HSV_VALUE // 0 (inclusive) to 1 (exclusive), defaulting to 0.65

Colour references

Often, multiple blocks share the same colour, and centralizing the colour definitions simplifies managing the colours and adding new blocks of the correct colour. Block colours can use string table references to do exactly that.

Blockly includes nine colour constants in the string table, coresponding to the toolbox categories, plus a distinct colour for dynamic variables:

'%{BKY_LOGIC_HUE}'
'%{BKY_LOOPS_HUE}'
'%{BKY_MATH_HUE}'
'%{BKY_TEXTS_HUE}'
'%{BKY_LISTS_HUE}'
'%{BKY_COLOUR_HUE}'
'%{BKY_VARIABLES_HUE}'
'%{BKY_VARIABLES_DYNAMIC_HUE}'
'%{BKY_PROCEDURES_HUE}'

These string values can be used in both the JSON definitions and block.setColour(..).

You can add your own colour constants by adding to Blockly.Msg:

// Define the colour
Blockly.Msg.EVERYTHING_HUE = 42;
// Use in a block or block definition:
block.setColour('%{BKY_EVERYTHING_HUE}');

Storing the colours in the localization string table, may seem unusual, but it is convenient given the JSON notation already has support for the references. It also allows colors to be localized, if desired.

The toolbox XML also supports such colour references in the category colour attribute:

<category name="Logic" colour="%{BKY_LOGIC_HUE}">
  ...
</category>

Customizing saturation and value

The saturation and values can be adapted for each application by overriding the following Blockly constants:

Blockly.HSV_SATURATION // 0 (inclusive) to 1 (exclusive), defaulting to 0.45
Blockly.HSV_VALUE // 0 (inclusive) to 1 (exclusive), defaulting to 0.65

Colour values in hex

Using the HSV colour space is highly recommended, but Blockly does support block colors specified as #RRGGBB hexidecimals. While this can faciliate coordination with other application colors (e.g., styles in CSS) and design applications (e.g., Photoshop), it is a design risk that could easily lead to uncoordinated blocks if not chosen carefully.

An example of poorly selected colors.

Unless you have dedicated visual design resources, working within the constraints of the HSV colour space is recommended. If attempting to redefine all colours in this manner, consider Google's Material Design resources on colour.

Accessibility concerns

Blockly uses colour as a strong hint about the role of each block, and to group blocks together. For the included blocks, this affordance is secondary to the text on the block, and so not a critical attribute. However, when choosing a block colour palette, colour blindness should be a consideration.

While Blockly does not have specific support for color blind accomodations, this page includes example 7, 12, and 15 color palettes that attempt to maximize distinction across the most common forms of color blindness. Note that this would not map to 7, 12, or 15 block categories in Blockly, because some shades should be reserved for shadow blocks and fields.