Themes are a way to customize the look and feel of Blockly. Currently we support customizing certain styles on blocks and categories. Our main goal in creating themes is to empower developers to create Blockly experiences that are more accessible.

However, with great power comes great responsibility. If there is no specific need to control all three style values for blocks (block colour, border colour, and shadow block colour) we highly encourage users to stick with using Blockly colours. It can be difficult to come up with colours that go well together so the easiest way to get started is still to define colours using hues and allow Blockly to calculate the colours of the border and shadow blocks.

Block Style

A block style is currently made up of four fields: colourPrimary, colourSecondary, colourTertiary, and hat.

Block with arrows pointing to primary, secondary and tertiary colour

    "colourPrimary": "#4a148c",

Primary Colour(required) -- This is used as the background colour of the block and can be defined in either hue or hex value.

Secondary Colour(optional) -- This colour is used if the block is a shadow block. This must be defined as a hex value.

Tertiary Colour(optional) -- This is the border colour of the block. Before themes the border colour was made up of a light and dark path in order to create a drop shadow effect. When the tertiary colour is defined it only uses one path for the border which creates a flat look(See image below). This value must be defined as a hex value.

Block with single border and block with shadow border

Hat(optional) -- This is used when the user wants to add a hat to their block. Currently, the only option for this value is "cap". Users can find out more information on hats and what they are used for here.

Category Style

A category style currently only holds a colour property.


Colour(required) -- This is the colour of the category on the flyout. This value can either be defined as a hex value or as a hue. Usually these colours should be the same as the colourPrimary on the majority of blocks in the category. This makes it easy for users to tell what blocks belong in what category.

Using Themes

In order to add a theme to your Blockly application there are three steps that need to be completed:

  • Create a Theme
  • Add Style Names
  • Set Your Theme

Create a Theme

A theme currently takes in both a map of block styles and a map of category styles. It also has the ability to change the colours of certain components.

Example Block Style Map

   "list_blocks": {
      "colourPrimary": "#4a148c",
   "logic_blocks": {
      "colourPrimary": "#01579b",

Example Category Style Map

   "list_category": {
      "colours": "#4a148c"
   "logic_category": {
      "colour": "#01579b",

To Create the Theme

var theme = Blockly.Theme(blockStyles, categoryStyles);

Set Component Styles

We currently support changing the colour of the below components:

  • workspace: The workspace background colour
  • toolbox: Toolbox background colour
  • toolboxText: Toolbox category text colour
  • flyout: Flyout background colour
  • flyoutText: Flyout label text colour
  • flyoutOpacity: Flyout opacity
  • scrollbar: Scrollbar colour
  • scrollbarOpacity: Scrollbar opacity

In order to change the colour of these components you can call yourTheme.setComponentStyle(componentName, componentValue). An example theme that changes the colour of these components can be found here.

These component names are not finalized and are still subject to change. If there is a component you would like to change that is not already a part of this list, please file an issue with more information here.

Add Style Names

Now that we have created a theme we need to add the name of the styles to the block and category definitions.


For categories just add the style tag to the xml.

<category name="Logic" categorystyle="logic_category">


How you define your block determines how you need to add the style name. You can find more on block definitions here.





Set your Theme

Now that you have created a theme and connected it to your blocks and categories , it is time to tell Blockly what theme to use.

Blockly Options

The best way to set an initial theme is by including options.theme in your inject call.

    theme: Blockly.Theme(blockStyles, categoryStyles)

More information on options can be found here. If no theme is provided then it will default to a Classic Theme which can be found in the themes folder here.

Blockly Set Theme

If you want to dynamically change your theme (for instance in the case of allowing users to choose a theme from a dropdown menu) then you can call yourWorkspace.setTheme(theme).

Create Block Styles Script

This script will take in a map of hues or hex values and will calculate the secondary and tertiary colours for them. The script can be found in the theme_script folder.


We currently have added a high contrast theme in order to increase readability. This style is not finalized and is subject to change. In the future we would like to add other themes for people who have different types of colour blindness.