Stay organized with collections
Save and categorize content based on your preferences.
Some icons have state that needs to be saved, while others are instantiated
based on existing state. For example, comment icons need to save their text,
while warning icons don't because they are instantiated based on how blocks are
connected.
If your icon needs to save its state, you need to implement the
ISerializable interface and register your
icon.
The state returned by your icon gets included in the icons property of your
block's state:
{'blocks':{'languageVersion':0,'blocks':[{'type':'my_block','icons':{// Your state goes here!'my_icon':'some state',}}]}}
Save state
To save the state of your icon, you need to implement the
saveState method of the ISerializable
interface. This method can return arbitrary json, which gets passed to your
loadState method.
saveState(){returnthis.state;// Some arbirtary JSON-compatible data.}
Full serialization and backing data
saveState also receives an optional doFullSerialization parameter. This is
used by icons that reference state serialized by a different
serializer (like backing data models). The parameter signals that
the referenced state won't be available when the block is deserialized, so the
icon should serialize all of the backing state itself. For example, this is true
when an individual block is serialized, or when a block is copy-pasted.
Two common use cases for this are:
When an individual block is loaded into a workspace where the backing data
model doesn't exist, the icon has enough information in its own state to
create a new data model.
When a block is copy-pasted, the icon always creates a new backing
data model instead of referencing an existing one.
Load state
To save the state of your icon, you need to implement the
loadState method of the ISerializable
interface. This method takes in the JSON returned by your saveState method.
loadState(state){this.state=state;}
Register icon classes
Finally you need to register your icon so that the serialization system can
instantiate it. Remember that the IconType used to register your
icon needs to have the same string as the one returned by its
getType method.
[[["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\u003eBlockly icons can optionally save their state for persistence, requiring the implementation of the \u003ccode\u003eISerializable\u003c/code\u003e interface and registration.\u003c/p\u003e\n"],["\u003cp\u003eIcon state is stored within the \u003ccode\u003eicons\u003c/code\u003e property of a block's state in JSON format, utilizing the \u003ccode\u003esaveState\u003c/code\u003e and \u003ccode\u003eloadState\u003c/code\u003e methods.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003esaveState\u003c/code\u003e method includes an optional \u003ccode\u003edoFullSerialization\u003c/code\u003e parameter to handle cases where the referenced data model isn't available during deserialization, for instance when loading or copying blocks.\u003c/p\u003e\n"],["\u003cp\u003eTo load saved icon state, implement the \u003ccode\u003eloadState\u003c/code\u003e method which receives the JSON data previously saved by \u003ccode\u003esaveState\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eFor the serialization system to instantiate your custom icon, register it using its corresponding \u003ccode\u003eIconType\u003c/code\u003e, ensuring consistency with the \u003ccode\u003egetType\u003c/code\u003e method's return value.\u003c/p\u003e\n"]]],["Icons that require saving state must implement the `ISerializable` interface and be registered. To save state, the `saveState` method returns JSON data, which is then used by the `loadState` method to restore the icon's state. The `saveState` method takes an optional `doFullSerialization` parameter for serializing referenced state. The state is stored under the `icons` property of the block's state. Icon classes must be registered using the same string as their `getType` method.\n"],null,["# Save and load icons\n\nSome icons have state that needs to be saved, while others are instantiated\nbased on existing state. For example, comment icons need to save their text,\nwhile warning icons don't because they are instantiated based on how blocks are\nconnected.\n\nIf your icon needs to save its state, you need to implement the\n[`ISerializable`](/blockly/reference/js/blockly.iserializable_interface) interface and [register](/blockly/guides/create-custom-blocks/icons/creating-custom-icons/save-and-load#register_icon_classes) your\nicon.\n\nThe state returned by your icon gets included in the `icons` property of your\nblock's state: \n\n {\n 'blocks': {\n 'languageVersion': 0,\n 'blocks': [\n {\n 'type': 'my_block',\n 'icons': {\n // Your state goes here!\n 'my_icon': 'some state',\n }\n }\n ]\n }\n }\n\n| **Important:** saving and loading custom icons does not work with the old XML serialization system, only the new JSON system.\n\nSave state\n----------\n\nTo save the state of your icon, you need to implement the\n[`saveState`](/blockly/reference/js/blockly.iserializable_interface.savestate_1_methodsignature) method of the [`ISerializable`](/blockly/reference/js/blockly.iserializable_interface)\ninterface. This method can return arbitrary json, which gets passed to your\n`loadState` method. \n\n saveState() {\n return this.state; // Some arbirtary JSON-compatible data.\n }\n\n### Full serialization and backing data\n\n`saveState` also receives an optional `doFullSerialization` parameter. This is\nused by icons that reference state serialized by a different\n[serializer](/blockly/guides/configure/web/serialization#serializer_hooks) (like backing data models). The parameter signals that\nthe referenced state won't be available when the block is deserialized, so the\nicon should serialize all of the backing state itself. For example, this is true\nwhen an individual block is serialized, or when a block is copy-pasted.\n\nTwo common use cases for this are:\n\n- When an individual block is loaded into a workspace where the backing data model doesn't exist, the icon has enough information in its own state to create a new data model.\n- When a block is copy-pasted, the icon always creates a new backing data model instead of referencing an existing one.\n\nLoad state\n----------\n\nTo save the state of your icon, you need to implement the\n[`loadState`](/blockly/reference/js/blockly.iserializable_interface.loadstate_1_methodsignature) method of the [`ISerializable`](/blockly/reference/js/blockly.iserializable_interface)\ninterface. This method takes in the JSON returned by your `saveState` method. \n\n loadState(state) {\n this.state = state;\n }\n\nRegister icon classes\n---------------------\n\nFinally you need to register your icon so that the serialization system can\ninstantiate it. Remember that the [`IconType`](/blockly/reference/js/blockly.icons_namespace.icontype_class) used to register your\nicon needs to have the same string as the one returned by its\n[`getType`](/blockly/reference/js/blockly.iicon_interface.gettype_1_methodsignature) method. \n\n class myIcon extends Blockly.icons.Icon {\n getType() {\n return new Blockly.icons.IconType('my_icon');\n }\n }\n\n Blockly.icons.registry.register(\n new Blockly.icons.IconType('my_icon'), myIcon);"]]