Skip to main content

Plugins

A plugin is a self-contained piece of code that adds functionality to Blockly. For example, it might add a custom field, define a new theme, or provide a custom renderer. Plugins are generally packaged and distributed through npm.

note

The BlocklyOptions object has a plugins property for injecting classes that customize Blockly behavior. While these classes may be implemented as plugins, this is not required and they are otherwise unrelated.

For a quick introduction to plugins, see our Plugins Overview talk (2021).

If you want to create your own plugin, see Add a plugin.

First- and third-party plugins​

First-party plugins are supported by the Blockly team and published under the @blockly scope on npm. They are designed to be usable in a wide range of Blockly applications.

Third-party plugins are maintained and published independently. They may be more complex, more experimental, or targeted to a narrower range of Blockly applications.

Find a plugin​

Install a plugin​

We recommend installing plugins with a package manager like npm or yarn. This makes it easy to receive updates.

  • Install a plugin with a package manager

    npm install @blockly/field-angle

  • Install a plugin without a package manager

    <script src="https://unpkg.com/@blockly/field-angle"></script>

    You can also clone the GitHub repository that contains the plugin. For first-party plugins, this is blockly.

Check the plugin's README to see if there are any additional installation instructions.

Use a plugin​

Each plugin is different, so see the plugin's README for information on how to use that plugin. The following example shows how to use the @blockly/field-angle plugin:

  1. Import code from the plugin. How you do this depends on how you installed the plugin.

    import Blockly from 'blockly';
    import {registerFieldAngle} from '@blockly/field-angle';

  2. Initialize the plugin as needed. Plugins that provide custom fields often require you to register the field:

    registerFieldAngle();

  3. Use the plugin.

    Blockly.common.defineBlocksWithJsonArray([
      {
        type: "my_angle_block",
        message0: "%1 degrees",
        args0: [
          {
            // Use @blockly/field-angle.
            type: "field_angle",
            name: "FIELDNAME",
            value: 45,
          },
        ],
        output: null,
        style: 'math_blocks'
      },
    ]);
    A field for picking an angle from a 360-degree dial.

Plugin versions​

Blockly uses semantic versioning, which requires breaking changes to use a new major version.

Any new plugin that monkey patches core will have a major version of 0 to signify initial development.

Most plugins include the blockly package as a peerDependency rather than a dependency. This is because we assume that you have already installed Blockly. (It doesn't make sense to use a plugin without using Blockly.) Starting with Blockly v13, first-party plugins share an exact version number with core Blockly. This means that in order to use a certain plugin, all you can simply check your Blockly version and use the same plugin version.

What if I'm using a major version of Blockly that's older than v13?

Keeping Blockly up-to-date is strongly reccomended, so that you get the newest features and fixes. However, if you can't upgrade Blockly, you can use the following npm command to list all of the pre-v13 versions of a plugin alongside the minimum Blockly version that they support:

npm view '@blockly/block-plus-minus@<13' peerDependencies.blockly

Just replace block-plus-minus with the name of whichever plugin you'd like to use.

When you add a plugin to your application's package.json, the default is to include a caret before the version:

"dependencies": {
  "@blockly/field-angle": "^13.2.1"
}

This will let npm install any minor version at or above the listed version, so version 13.3.1 or 13.2.6 works, but a new major version such as 14.0.1 would not. When you update to a major version of Blockly, you should update your plugins as well.