# @blockly/field-colour

> A Blockly colour field.

Latest version **13.3.0** (published 2026-09-10) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @blockly/field-colour
pnpm add @blockly/field-colour
yarn add @blockly/field-colour
bun add @blockly/field-colour
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score; popular repo.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 13.3.0 |
| Published | 2026-09-10 |
| First published | 2023-05-25 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 222 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 13572 |
| Author | Blockly Team |
| Maintainers | gonfunko, greg-rpf, raspberry-pi, lizschwab, maribethb |
| Keywords | blockly, field, colour |

## Links

- npm: https://www.npmjs.com/package/@blockly/field-colour
- Repository: https://github.com/RaspberryPiFoundation/blockly
- Homepage: https://github.com/RaspberryPiFoundation/blockly/tree/main/packages/plugins/field-colour#readme
- Issues: https://github.com/RaspberryPiFoundation/blockly/issues
- npm.io page: https://npm.io/package/@blockly/field-colour

## Dependencies (1)

- [@blockly/field-grid-dropdown](https://npm.io/package/@blockly/field-grid-dropdown.md) ^13.3.0

## Alternatives

- [postcss-color-hex-alpha](https://npm.io/package/postcss-color-hex-alpha.md) — 6.4M weekly downloads
- [randomcolor](https://npm.io/package/randomcolor.md) — 348.0K weekly downloads
- [bows](https://npm.io/package/bows.md) — 1.3K weekly downloads
- [ep_prefer_color_scheme](https://npm.io/package/ep_prefer_color_scheme.md) — 260 weekly downloads
- [coc-yank](https://npm.io/package/coc-yank.md) — 61 weekly downloads

## Recent versions

- 13.3.0 (latest) — 2026-09-10
- 13.2.2-beta.2 (beta) — 2026-08-11
- 13.2.2-beta.0 — 2026-08-11
- 13.2.0 — 2026-07-28
- 13.1.0 — 2026-06-30
- 6.0.12 — 2026-04-09
- 6.0.11 — 2026-01-15
- 6.0.10 — 2026-01-05
- 6.0.8 — 2025-12-19
- 6.0.7 — 2025-12-19
- 6.0.6 — 2025-10-30
- 6.0.5 — 2025-10-02
- 6.0.4 — 2025-07-17
- 6.0.3 — 2025-07-03
- 6.0.2 — 2025-06-19
- … 39 more at https://npm.io/package/@blockly/field-colour/versions

## README

# @blockly/field-colour [![Built on Blockly](https://tinyurl.com/built-on-blockly)](https://github.com/google/blockly)

A [Blockly](https://www.npmjs.com/package/blockly) field and blocks for
choosing and combining colours.

## Installation

### Yarn

```
yarn add @blockly/field-colour
```

### npm

```
npm install @blockly/field-colour --save
```

## Usage

If you want to use this field in a block definition, you must install it by
calling `registerFieldColour` before instantiating your blocks. If another
field is registered under the same name (`field_colour`), this field will
overwrite it.

If you [install the blocks](#blocks) in this package, the field will
automatically be installed.

### Field

The colour field stores a string as its `value`, and a string as its `text`. Its
`value` is a string with the format `#rrggbb`, while its `text` may be a string
with the format `#rgb` if possible.

#### Colour field

![](https://github.com/RaspberryPiFoundation/blockly/raw/main/packages/plugins/field-colour/readme-media/on_block.png)

#### Colour field with editor open

![](https://github.com/RaspberryPiFoundation/blockly/raw/main/packages/plugins/field-colour/readme-media/with_editor.png)

#### Colour field on collapsed block

![](https://github.com/RaspberryPiFoundation/blockly/raw/main/packages/plugins/field-colour/readme-media/collapsed.png)

### Creation

#### JavaScript

```js
import * as Blockly from 'blockly';
import {registerFieldColour} from '@blockly/field-colour';

registerFieldColour();
Blockly.Blocks['test_field_colour'] = {
  init: function () {
    this.appendDummyInput()
      .appendField('colour: ')
      .appendField(
        new FieldColour('#ff4040', null, {
          colourOptions: [
            '#ff4040',
            '#ff8080',
            '#ffc0c0',
            '#4040ff',
            '#8080ff',
            '#c0c0ff',
          ],
          colourTitles: [
            'dark pink',
            'pink',
            'light pink',
            'dark blue',
            'blue',
            'light blue',
          ],
          columns: 3,
        }),
        'FIELDNAME',
      );
  },
};
```

#### JSON

```js
import * as Blockly from 'blockly';
import {registerFieldColour} from '@blockly/field-colour';

registerFieldColour();
Blockly.defineBlocksWithJsonArray([
  {
    type: 'test_field_colour',
    message0: 'colour: %1',
    args0: [
      {
        type: 'field_colour',
        name: 'FIELDNAME',
        colour: '#ff4040',
        colourOptions: [
          '#ff4040',
          '#ff8080',
          '#ffc0c0',
          '#4040ff',
          '#8080ff',
          '#c0c0ff',
        ],
        colourTitles: [
          'dark pink',
          'pink',
          'light pink',
          'dark blue',
          'blue',
          'light blue',
        ],
        columns: 3,
      },
    ],
  },
]);
```

The colour constructor takes in the following:

- an optional `value`
- an optional [validator](#creating-a-colour-validator)
- an optional map of options, including:
  - `colourOptions`
  - `colourTitles`
  - `columns`

The `value` should be a string in the format `#rrggbb`. If no `value`
is given or the given `value` is invalid, the first entry in the
default colours array will be used.

The following options can also be set in JSON:

- `colourOptions`
- `colourTitles`
- `columns`

Or they can be set using [JavaScript hooks](#editor-options).

## Customization

### Editor options

The `setColours`
function can be used to set the colour options of a colour field. It takes in an
array of colour strings, which must be defined in `#rrggbb` format, and an
optional array of tooltips. If the tooltip array is not provided, the default
tooltip array will be used.

Tooltips and colours are matched based on array index, not based on value. If
the colours array is longer than the tooltip array, the tooltips for the extra
colours will be their `#rrggbb` value.

The setColumns function sets the number of columns in the colour picker.

#### JSON

```js
{
  "type": "example_colour",
  "message0": "colour: %1",
  "args0": [
    {
      "type": "field_colour",
      "name": "COLOUR",
      "colour": "#ff4040"
    }
  ],
  "extensions": ["set_colours_extension"]
}
```

```js
Blockly.Extensions.register('set_colours_extension', function () {
  var field = this.getField('COLOUR');
  field.setColours(
    ['#ff4040', '#ff8080', '#ffc0c0', '#4040ff', '#8080ff', '#c0c0ff'],
    ['dark pink', 'pink', 'light pink', 'dark blue', 'blue', 'light blue'],
  );
  field.setColumns(3);
});
```

This is done using a JSON
[extension](https://docs.blockly.com/guides/create-custom-blocks/define/extensions/).

#### JavaScript

```js
Blockly.Blocks['example_colour'] = {
  init: function () {
    var field = new Blockly.FieldColour('#ff4040');
    field.setColours(
      ['#ff4040', '#ff8080', '#ffc0c0', '#4040ff', '#8080ff', '#c0c0ff'],
      ['dark pink', 'pink', 'light pink', 'dark blue', 'blue', 'light blue'],
    );
    field.setColumns(3);
    this.appendDummyInput().appendField('colour:').appendField(field, 'COLOUR');
  },
};
```

![Customized colour field editor](https://github.com/RaspberryPiFoundation/blockly/raw/main/packages/plugins/field-colour/readme-media/customized.png)

#### Creating a colour validator

Note: For information on validators in general see [Validators](https://docs.blockly.com/guides/create-custom-blocks/fields/validators/).

A colour field's value is a `#rrggbb` format string, so any validators must
accept a `#rrggbb` format string, and return a `#rrggbb` format string, `null`,
or `undefined`.

Here is an example of a validator that changes the colour of the block to match
the colour of the field.

```
function(newValue) {
  this.getSourceBlock().setColour(newValue);
  return newValue;
}
```

#### Block changing colour based on its colour field

![](https://github.com/RaspberryPiFoundation/blockly/raw/main/packages/plugins/field-colour/readme-media/validator.gif)

### Blocks

This package also provides four blocks related to the colour field. Each block
has generators in JavaScript, Python, PHP, Lua, and Dart.

- "colour_blend" takes in two colours and a ratio and outputs a single colour.
- "colour_picker" is a simple block with just the colour field and an output.
- "colour_random" generates a random colour.
- "colour_rgb" generates a colour based on red, green, and blue values.

You can install all four blocks by calling `installAllBlocks`. This will
install the blocks and all of their dependencies, including the colour field.
When calling `installAllBlocks`—or any of the individual `installSomeBlock`
functions—you can supply one or more `CodeGenerator` instances (e.g.
`javascriptGenerator`), and the install function will also install the correct
generator function for each block for the corresponding language(s).

```js
import {javascriptGenerator} from 'blockly/javascript';
import {dartGenerator} from 'blockly/dart';
import {phpGenerator} from 'blockly/php';
import {pythonGenerator} from 'blockly/python';
import {luaGenerator} from 'blockly/lua';
import {installAllBlocks as installColourBlocks} from '@blockly/field-colour';

// Installs all four blocks, the colour field, and all language generators.
installColourBlocks({
  javascript: javascriptGenerator,
  dart: dartGenerator,
  lua: luaGenerator,
  python: pythonGenerator,
  php: phpGenerator,
});
```

If you only want to install a single block, you can call that block's
`installBlock` function. The `generators` parameter is the same.

```js
import {javascriptGenerator} from 'blockly/javascript';
import {colourBlend} from '@blockly/field-colour';

// Installs the colour_blend block, the colour field,
// and the generator for colour_blend in JavaScript.
colourBlend.installBlock({
  javascript: javascriptGenerator,
});
```

#### Message files and locales

The blocks in this package contain text that can be localized into multiple
languages. As of August 2024, the relevant messages are included in the core
Blockly language files. For information on Blockly's approach to localization,
see [Localization](https://docs.blockly.com/guides/configure/translations/)
in the developer's guide.

If your blocks show `%{BKY_COLOUR_BLEND_TITLE}` or similar text instead
of the expected text, make sure that you either:

- Import the default Blockly modules, which includes the English langfiles, or
- Explicitly import a language and call `setLocale` before using these blocks.

For more information, see [Load a Blockly localization
table](https://docs.blockly.com/guides/configure/translations/#load-blockly).

### API Reference

- `setColours`: Sets the colour options, and optionally the titles for the
  options. The colours should be an array of `#rrggbb` strings.
- `setColumns`: Sets the number of columns the dropdown should have.

## License

Apache 2.0

---
_Source: https://npm.io/package/@blockly/field-colour · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._