Use pop-up bubbles
Stay organized with collections
Save and categorize content based on your preferences.
The built-in icons use a pop-up-bubble-style UI to display extra information or
editors. Custom icons can also replicate this behavior, to maintain a
consistent look-and-feel.
If your icon should show a bubble, you need to implement the
IHasBubble
interface.
Show or hide the bubble
Icons that use bubbles should implement the
setBubbleVisible
method to show or hide the bubble.
// Implement the setBubbleVisible method of the IHasBubble interface.
async setBubbleVisible(visible) {
// State is already correct.
if (!!this.myBubble === visible) return;
// Wait for queued renders to finish so that the icon will be correctly
// positioned before displaying the bubble.
await Blockly.renderManagement.finishQueuedRenders();
if (visible) {
this.myBubble = new MyBubble(this.getAnchorLocation(), this.getOwnerRect());
} else {
this.myBubble?.dispose();
}
}
// Implement helper methods for getting the anchor location and bounds.
// Returns the location of the middle of this icon in workspace coordinates.
getAnchorLocation() {
const size = this.getSize();
const midIcon = new Blockly.utils.Coordinate(size.width / 2, size.height / 2);
return Blockly.utils.Coordinate.sum(this.workspaceLocation, midIcon);
}
// Returns the rect the bubble should avoid overlapping, i.e. the block this
// icon is appended to.
getOwnerRect() {
const bbox = this.sourceBlock.getSvgRoot().getBBox();
return new Blockly.utils.Rect(
bbox.y, bbox.y + bbox.height, bbox.x, bbox.x + bbox.width);
}
Deal with dragging the block
When the icon changes location, the bubble does not automatically move with it.
You either need to update the location of the bubble, or hide it. This can be
done inside the onLocationChange
method of the
IIcon
interface.
onLocationChange(blockOrigin) {
super.onLocationChange(blockOrigin);
this.myBubble?.setAnchorLocation(this.getAnchorLocation());
}
Return the visibility of the bubble
The IHasBubble
interface also requires that you implement an
bubbleIsVisible
method that returns whether the bubble is
visible or not.
isBubbleVisible() {
return !!this.myBubble;
}
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-05-23 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-05-23 UTC."],[[["\u003cp\u003eBlockly's built-in icons use a pop-up bubble UI for extra information, and custom icons can be designed to maintain this consistent behavior.\u003c/p\u003e\n"],["\u003cp\u003eCustom icons with bubbles need to implement the \u003ccode\u003eIHasBubble\u003c/code\u003e interface including methods to show/hide the bubble and update its position.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003esetBubbleVisible\u003c/code\u003e method controls the bubble's visibility, while \u003ccode\u003eonLocationChange\u003c/code\u003e ensures the bubble moves with the icon when the block is dragged.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers need to provide methods like \u003ccode\u003egetAnchorLocation\u003c/code\u003e and \u003ccode\u003egetOwnerRect\u003c/code\u003e to correctly position the bubble relative to the icon and block.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eisBubbleVisible\u003c/code\u003e method is required to report the current visibility status of the bubble.\u003c/p\u003e\n"]]],["Custom icons can use a pop-up bubble UI by implementing the `IHasBubble` interface. To show or hide the bubble, implement the `setBubbleVisible` method, managing bubble creation and disposal. Implement `getAnchorLocation` and `getOwnerRect` to position the bubble. The `onLocationChange` method should update the bubble's position when the icon moves. The `isBubbleVisible` method is used to report the bubble's current visibility state. These methods ensure consistent bubble behavior.\n"],null,["# Use pop-up bubbles\n\nThe built-in icons use a pop-up-bubble-style UI to display extra information or\neditors. Custom icons can also replicate this behavior, to maintain a\nconsistent look-and-feel.\n\nIf your icon should show a bubble, you need to implement the\n[`IHasBubble`](/blockly/reference/js/blockly.ihasbubble_interface) interface.\n\nShow or hide the bubble\n-----------------------\n\nIcons that use bubbles should implement the\n[`setBubbleVisible`](/blockly/reference/js/blockly.ihasbubble_interface.setbubblevisible_1_methodsignature) method to show or hide the bubble. \n\n // Implement the setBubbleVisible method of the IHasBubble interface.\n async setBubbleVisible(visible) {\n // State is already correct.\n if (!!this.myBubble === visible) return;\n\n // Wait for queued renders to finish so that the icon will be correctly\n // positioned before displaying the bubble.\n await Blockly.renderManagement.finishQueuedRenders();\n\n if (visible) {\n this.myBubble = new MyBubble(this.getAnchorLocation(), this.getOwnerRect());\n } else {\n this.myBubble?.dispose();\n }\n }\n\n // Implement helper methods for getting the anchor location and bounds.\n\n // Returns the location of the middle of this icon in workspace coordinates.\n getAnchorLocation() {\n const size = this.getSize();\n const midIcon = new Blockly.utils.Coordinate(size.width / 2, size.height / 2);\n return Blockly.utils.Coordinate.sum(this.workspaceLocation, midIcon);\n }\n\n // Returns the rect the bubble should avoid overlapping, i.e. the block this\n // icon is appended to.\n getOwnerRect() {\n const bbox = this.sourceBlock.getSvgRoot().getBBox();\n return new Blockly.utils.Rect(\n bbox.y, bbox.y + bbox.height, bbox.x, bbox.x + bbox.width);\n }\n\nDeal with dragging the block\n----------------------------\n\nWhen the icon changes location, the bubble does not automatically move with it.\nYou either need to update the location of the bubble, or hide it. This can be\ndone inside the [`onLocationChange`](/blockly/reference/js/blockly.iicon_interface.onlocationchange_1_methodsignature) method of the\n[`IIcon`](/blockly/reference/js/blockly.iicon_interface) interface. \n\n onLocationChange(blockOrigin) {\n super.onLocationChange(blockOrigin);\n this.myBubble?.setAnchorLocation(this.getAnchorLocation());\n }\n\nReturn the visibility of the bubble\n-----------------------------------\n\nThe [`IHasBubble`](/blockly/reference/js/blockly.ihasbubble_interface) interface also requires that you implement an\n[`bubbleIsVisible`](/blockly/reference/js/blockly.ihasbubble_interface.bubbleisvisible_1_methodsignature) method that returns whether the bubble is\nvisible or not. \n\n isBubbleVisible() {\n return !!this.myBubble;\n }"]]