Custom blocks overview
Stay organized with collections
Save and categorize content based on your preferences.
Blockly comes with a large number of predefined blocks, from mathematical
functions to looping structures. However, most applications need to define and
implement custom blocks for their domain. For example, a drawing application
might need blocks to draw lines and circles and a robotics application might
need blocks to move an arm and manipulate a claw.
To define and use a new type of block, you need three things:
- Block definition: Defines the look and feel of a block type as well as
certain behaviors.
- Block-code generator: Generates the code string for blocks of this type.
It is always written in JavaScript, even if the target language is not
JavaScript.
- Toolbox reference: A reference to the block type in the toolbox, so
users can add it to the workspace.
Block definition
A block definition defines the look and feel of a block, such as its text,
fields, connections, and colour. It can also define block-specific behavior,
such as a block-specific event handler. For example, this block:

can be defined in JSON or JavaScript as follows:
JSON
Blockly.common.defineBlocksWithJsonArray([{
"type": "string_length",
"message0": 'length of %1',
"args0": [
{
"type": "input_value",
"name": "VALUE",
"check": "String"
}
],
"output": "Number",
"colour": 160,
"tooltip": "Returns number of letters in the provided text.",
"helpUrl": "http://www.w3schools.com/jsref/jsref_length_string.asp"
}]);
JavaScript
Blockly.Blocks['string_length'] = {
init: function() {
this.appendValueInput('VALUE')
.setCheck('String')
.appendField('length of');
this.setOutput(true, 'Number');
this.setColour(160);
this.setTooltip('Returns number of letters in the provided text.');
this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');
}
};
For more information about block definitions and how they work, see What's a
block
definition?.
Block-code generators
To transform a block into code, you need separate generator functions for each
language you want to generate. For example, here is a generator that generates
JavaScript:
javascriptGenerator.forBlock['string_length'] = function(block, generator) {
// String or array length.
var argument0 = generator.valueToCode(block, 'VALUE', Order.FUNCTION_CALL) || '\'\'';
return [argument0 + '.length', Order.MEMBER];
};
The generator function accepts the block being processed and a language
generator. It generates code for any blocks attached to inputs (such as the
VALUE
input in the example) and any fields, and then concatenates the
resulting strings into a larger expression.
For more information, see Block-code
generators.
After you have defined your block type, use the type name to reference it in a
toolbox:
JSON
var toolbox = {
"kind": "categoryToolbox",
"name": "Text"
"contents": [
{
"kind": "block",
"type": "string_length"
},
]
};
XML
<xml id="toolbox" style="display: none"> WHY IS THERE DISPLAY: NONE HERE?
<category name="Text">
<block type="string_length"></block>
</category>
...
</xml>
For more information, see Define a flyout
toolbox or Define a category
toolbox.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-04-14 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-04-14 UTC."],[[["\u003cp\u003eThis documentation guides developers on creating custom blocks within Blockly, assuming basic JavaScript knowledge and Blockly familiarity.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can create new blocks by defining their shape and connections using Blockly Developer Tools or by manually coding them using the API.\u003c/p\u003e\n"],["\u003cp\u003eCustom blocks require code generators to translate them into target programming languages like JavaScript or Python.\u003c/p\u003e\n"],["\u003cp\u003eAfter creation, custom blocks need to be integrated into the Blockly toolbox or workspace for usage.\u003c/p\u003e\n"]]],["Developers creating custom blocks in Blockly should first define the block's shape, fields, and connections, ideally using Blockly Developer Tools. Next, a block-code generator is needed to translate the block into a programming language. Advanced blocks can use mutators to dynamically change shape. Finally, the new block must be added to the toolbox or used in a workspace for it to be accessible within the application. The document assumes the user has a local copy of Blockly and a basic Javascript knowledge.\n"],null,["Blockly comes with a large number of predefined blocks, from mathematical\nfunctions to looping structures. However, most applications need to define and\nimplement custom blocks for their domain. For example, a drawing application\nmight need blocks to draw lines and circles and a robotics application might\nneed blocks to move an arm and manipulate a claw.\n\nTo define and use a new type of block, you need three things:\n\n- **Block definition**: Defines the look and feel of a block type as well as certain behaviors.\n- **Block-code generator**: Generates the code string for blocks of this type. It is always written in JavaScript, even if the target language is not JavaScript.\n- **Toolbox reference**: A reference to the block type in the toolbox, so users can add it to the workspace.\n\nBlock definition\n\nA **block definition** defines the look and feel of a block, such as its text,\nfields, connections, and colour. It can also define block-specific behavior,\nsuch as a block-specific event handler. For example, this block:\n\ncan be defined in JSON or JavaScript as follows: \n\nJSON \n\n Blockly.common.defineBlocksWithJsonArray([{\n \"type\": \"string_length\",\n \"message0\": 'length of %1',\n \"args0\": [\n {\n \"type\": \"input_value\",\n \"name\": \"VALUE\",\n \"check\": \"String\"\n }\n ],\n \"output\": \"Number\",\n \"colour\": 160,\n \"tooltip\": \"Returns number of letters in the provided text.\",\n \"helpUrl\": \"http://www.w3schools.com/jsref/jsref_length_string.asp\"\n }]);\n\nJavaScript \n\n Blockly.Blocks['string_length'] = {\n init: function() {\n this.appendValueInput('VALUE')\n .setCheck('String')\n .appendField('length of');\n this.setOutput(true, 'Number');\n this.setColour(160);\n this.setTooltip('Returns number of letters in the provided text.');\n this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');\n }\n };\n\nFor more information about block definitions and how they work, see [What's a\nblock\ndefinition?](/blockly/guides/create-custom-blocks/define/block-definitions).\n\nBlock-code generators\n\nTo transform a block into code, you need separate generator functions for each\nlanguage you want to generate. For example, here is a generator that generates\nJavaScript: \n\n javascriptGenerator.forBlock['string_length'] = function(block, generator) {\n // String or array length.\n var argument0 = generator.valueToCode(block, 'VALUE', Order.FUNCTION_CALL) || '\\'\\'';\n return [argument0 + '.length', Order.MEMBER];\n };\n\nThe generator function accepts the block being processed and a language\ngenerator. It generates code for any blocks attached to inputs (such as the\n`VALUE` input in the example) and any fields, and then concatenates the\nresulting strings into a larger expression.\n\nFor more information, see [Block-code\ngenerators](/blockly/guides/create-custom-blocks/code-generation/block-code).\n\nToolbox reference\n\nAfter you have defined your block type, use the type name to reference it in a\ntoolbox: \n\nJSON \n\n var toolbox = {\n \"kind\": \"categoryToolbox\",\n \"name\": \"Text\"\n \"contents\": [\n {\n \"kind\": \"block\",\n \"type\": \"string_length\"\n },\n ]\n };\n\nXML \n\n \u003cxml id=\"toolbox\" style=\"display: none\"\u003e WHY IS THERE DISPLAY: NONE HERE?\n \u003ccategory name=\"Text\"\u003e\n \u003cblock type=\"string_length\"\u003e\u003c/block\u003e\n \u003c/category\u003e\n ...\n \u003c/xml\u003e\n\nFor more information, see [Define a flyout\ntoolbox](/blockly/guides/configure/web/toolboxes/flyout) or [Define a category\ntoolbox](/blockly/guides/configure/web/toolboxes/category)."]]