Add-on SDK FAQ: Widgets & Panels

Recently I noticed a recurring theme in questions posted on the Jetpack group as well as on Stack Overflow. People want to associate a panel with a widget so that when the Widget icon is clicked, the Panel opens and is visually anchored to the widget icon:

In the questions we’ve seen, developers typically are trying to accomplish this by calling the panel object’s ‘show()’ method with the optional anchor argument:

A handle to a DOM node in a page to which the panel should appear to be anchored. If not given, the panel is centered inside the most recent browser window. Note that it is not currently possible to anchor panels in this way using only the high level APIs.


There are actually 2 problems with this:

  1. Currently anchoring panels to Dom nodes as described doesn’t work using addon-kit only; instead you need to require chrome in order to get access to a given page’s DOM. Please see this bug to track the issue. Update: Here is an example of how to do this using a low-level implementation. Warning! This sort of tomfoolery may break with later versions of the SDK.
  2. Even after the above bug is resolved, this technique won’t work for panels due to the fact that neither the widget itself nor any markup inside the widget’s ‘content’ property are in a browser tab.

The best solution for anchoring panels to widgets is instead to first create your panel, then supply the panel object as an option when creating your widget. Here is a simple example that anchors a panel to a widget:

const self = require("self");
/* Step 1: create the panel */
const panel = require("panel").Panel({
  width: 240,
  height: 320,
/* Step 2: create the widget, supplying the panel you just created */
const widget = require("widget").Widget({
  id: "some-id",
  label: "Some label",
  panel: panel

You can see this code in action in this very simple example addon-on hosted on the Add-on Builder:

There are currently some limitations with using this technique, however:

1. You can show the panel programmatically, however it will not be displayed nicely anchored to your widget, instead it will be appear in the center of the window. This example add-on exhibits the difference in behaviour:

2. The visual ‘anchoring’ effect only works if you supply the panel object when creating the widget. You can add a panel to a widget afterwards, but when you show it the panel will again be centered. See this Builder example:

These limitations are present in Add-on SDK version 1.0, however the project is considering ways to make this more flexible in the future. We’re tracking the issue in this bug:

Feel free to add yourself to the cc list if this issue is important to you, and as always please post to the Jetpack group or #jetpack on if you want to join the discussion.

Note: this post concerns features in the Add-on SDK version 1.0; if you’re reading this from the future, things have probably changed in your present.

4 responses

  1. Mingyi wrote on :

    I figured out a way to anchor the reopened panel to widget – you can take a look at my Fastest Search addon v1.61 at for the behavior:

    When you open Options Panel by clicking Fastest Search icon, the panel is anchored to widget. Then when you click on any blue ‘?’ in the Options Panel, a JS alert box shows up, and when you click ‘OK’, the panel reappears and is still anchored at widget.

    This is my hack:‘’));

    Where ‘’ is my addon id, ‘fastestsearch-icon’ is the widget id. I know my hack might fail in the future but for now, it works like a charm!

  2. Mingyi wrote on :

    Sorry, my uploading v1.62 caused the v1.61 link in my earlier post to stop working. You can always check the behavior by getting the latest version of Fastest Search at if needed. Would the OP please update the link in my previous post?

  3. tony wrote on :

    I tried to create a widget with html in it, but when I try to add the java script and css for the completeness function in my html not work, please give me an example for a widget or panel with html, java script and css that could work well : ‘(

  4. GJ wrote on :

    I am looking forward to this feature being added to the SDK. Is there an ETA for this?