addon.tab.appendToSharedSpace

The shared spaces API provides a standard way for addons to add their own custom UI elements to areas (“spaces”) inside Scratch.

For example, both the “mouse position” and “clone counter” addons add their own HTML elements to the project player stage header, after the stop button.

If a suitable shared space exists, addons should not use typical DOM methods to add their own elements to a specific section of the page, such as parentElement.appendChild(ownElement). Instead, addons should use shared spaces by calling this method.
See below for more information, and a list of existing shared spaces.

Example

As an example, this is how the “pause button” addon could be adding an element to the afterGreenFlag space:

// Creating an element and listening to events works like usually
const pauseButton = document.createElement("img");
pauseButton.src = addon.self.dir + "/play.svg";
pauseButton.addEventListener("click", changePauseState);

// Wait until the stage header exists before adding the pause button, like usually
await addon.tab.waitForElement("[class^='green-flag']");

// This number was reserved for the pause button.
// No other addon should use this order number in the `afterGreenFlag` space.
const PAUSE_BUTTON_ORDER_NUMBER = 0;

// appendToSharedSpace is used below, instead of typical element.appendChild()
addon.tab.appendToSharedSpace({
  space: "afterGreenFlag",
  element: pauseButton,
  order: PAUSE_BUTTON_ORDER_NUMBER
});

Description

Order numbers prevent adding new UI elements from being a racy operation, where users would observe that the order of UI elements added by third-party browser extensions varies unpredictably on each page session.

Regarding order numbers

  • Each shared space has its own order number set, independent from all other shared spaces.
  • Order numbers are typically positive integers, but negative and decimal numbers are also supported.
  • The element with the lowest number will always become the first child of the corresponding HTML element.
  • Any addon can theoretically call this method with any order number, and no error will be thrown. Order numbers aren’t logically reserved. Developers are in charge of making sure each addon is calling this method with a suitable order number.
  • Multiple order numbers may be reserved for a single addon within a shared space.
  • In some cases, 2 or more addons may use the same order number within the same shared space, as long as only one of the elements can be visible at once.
This API does not remove the need to wait until the shared space HTML element exists, if applicable. The addon.tab.waitForElement method is still necessary in most situations.

Defining shared spaces

The list of existing shared spaces is hardcoded inside the code definition of the method (addon-api/content-script/Tab.js).
Each shared space has a name, and is defined by these properties:

  1. Space parent element: the HTML element where addons would typically add their UI elements inside of. This will be the parent element of all elements added to the shared space.
  2. Space starting bound (optional): the sibling after which shared space items should always be added.
  3. Space ending bound (optional): the sibling before which shared space items should always be added.
  4. Accepts scope option: whether a space can exist multiple times per page. In those cases, addons should manually provide an HTML element that contains the wanted parent element.

As an example, the definition of the afterGreenFlag shared space calls document.querySelector('div[class^="controls_controls-container"]') to find the space parent element. Additionally, this space does not use the scope option, because there can only be 1 project player per document.

If more than 1 addon is adding custom UI elements inside the same HTML parent element, a shared space must be created.
In cases where only one addon is adding custom UI elements, it’s not necessary to create a space for it.

Method

ParameterTypeRequiredDescription
optionsObjectYes
PropertyTypeRequiredDescription
spacestringYesThe name of the space where the element should be added (see list below).
elementHTMLElementYesThe element that should be added to the space.
ordernumberYesThe order number for the element.
scopeHTMLElementUsually not.
Only for some spaces.
The specific element where the shared space item should be added inside of, for spaces that appear multiple times per page.
Return valueboolean
DescriptionWhether the element was added. Typically ignored.

List of shared spaces

Scratch editor spaces

stageHeader

Elements added to this space will be positioned next to the “small stage” and “big stage” buttons.
This is typically the right side of the stage header. This might not be true in RTL languages, or if the editor-buttons-reverse-order addon is enabled.

Shared space image

This shared space may exist in 5 different situations:

  1. Project in editor mode, small stage disabled (default).
  2. Project in editor mode, small stage enabled. Elements from this space are often hidden in this situation.
  3. Project in editor mode, hide-stage addon functionality triggered by the user.
  4. Project in projectpage mode.
  5. Project in embed mode.

This shared space will not exist while on fullscreen mode. See fullscreenStageHeader.

Typical CSS properties: margin-right: 0.2rem (LTR), margin-left: 0.2rem (RTL)

Space parent elementdiv[class^="stage-header_stage-size-row"]
Space starting boundNone
Space ending bound"Small stage" button or "full screen" button
scope option used
Addon IDElementOrder numberVisibility in small stage mode
debuggerDebugger button0Hidden
gamepadGamepad button1Hidden

fullscreenStageHeader

See stageHeader. Full screen can be triggered both from the project page and from inside the editor.

Shared space image

Typical CSS properties: margin-right: 0.2rem (LTR), margin-left: 0.2rem (RTL)

Space parent elementdiv[class^="stage-header_stage-menu-wrapper"]
Space starting boundNone
Space ending bound"Full screen" button
scope option used
Addon IDElementOrder number
gamepadGamepad button0

afterGreenFlag

Elements added to this space will be positioned between the green flag and the stop button.
This space will exist in all situations where a project player also exists.

Shared space image

Typical CSS properties: padding: 0.375rem

Space parent elementdiv[class^="controls_controls-container"]
Space starting boundGreen flag button
Space ending boundStop button
scope option used
Addon IDElementOrder numberVisibility in small stage mode
pausePause button0Visible

afterStopButton

Elements added to this space will be positioned after the project control buttons.
This space will exist in all situations where a project player also exists.

Shared space image

Typical CSS properties: padding-left: 0.25rem; padding-right: 0.25rem

Space parent elementdiv[class^="controls_controls-container"]
Space starting boundStop button
Space ending boundNone
scope option used
Addon IDElementOrder numberVisibility in small stage mode
mute-projectMuted project indicator (only visible if vol-slider disabled)0Visible
vol-sliderMuted project indicator and volume slider0Hidden
mouse-posMouse coordinates1Hidden
clone-countClone count2Hidden

afterSoundTab

Elements added to this space will be positioned after the “sounds” tab.

Shared space image

Typical DOM classes for elements added to this space: addon.tab.scratchClass("react-tabs_react-tabs__tab", "gui_tab")

The order number typically matches the reserved value for redux.state.scratchGui.editorTab.activeTabIndex.

Space parent elementdiv[class^="react-tabs_react-tabs__tab-list"]
Space starting bound"Sounds" tab
Space ending boundSearch bar added by find-bar addon
scope option used
Addon IDElementOrder number
variable-manager"Variables" tab3

Scratch website spaces

afterCopyLinkButton

Elements added to this space will be positioned after the “copy link” button in project pages.

Shared space image

Typical DOM classes for elements added to this space: button, action-button

Space parent element.flex-row.action-buttons
Space starting bound"Copy link" button
Space ending boundNone
scope option used
Addon IDElementOrder number
remix-tree-button"Remix tree" button0

beforeRemixButton

Elements added to this space will be positioned before the “remix” or “see inside” buttons in project pages.

Shared space image

Space parent elementdiv.project-buttons
Space starting boundNone
Space ending bound"Remix" button or "see inside" button
scope option used
Addon IDElementOrder number
project-infoSprite and script count0
turbowarp-playerTurboWarp button1
remix-buttonRemix button (only visible in own projects)9

Scratch forums spaces

forumsBeforePostReport

Elements added to this space will be positioned before the “report” button in a specific post.

Shared space image

If the “report” button does not exist (user is logged out), a visible placeholder dot will be added to the post automatically to act as a separator between the forumsBeforePostReport and forumsAfterPostReport spaces.

Addition of the | separator is handled by the shared spaces API.

Space parent element.postfootright > ul
Space starting boundNone
Space ending bound"Report" button
scope option used✔️ (usually a div.blockpost)
Addon IDElementOrder number
my-ocularReactions0
my-ocularReaction menu1
my-ocularView in Ocular button2
hide-signatures"Show signature" button9
forum-id"Quote post number" button10

forumsAfterPostReport

Elements added to this space will be positioned after the “report” button in a specific post.

Shared space image

See forumsBeforePostReport for more information.

Space parent element.postfootright > ul
Space starting bound"Report" button
Space ending boundNone
scope option used✔️ (usually a div.blockpost)
Addon IDElementOrder number
show-bbcodeShow BBCode button0