SelectorGadget: a CSS selector bookmarklet with a replaceable interface

A bookmarklet for pages that resist ordinary inspection

SelectorGadget is an open source bookmarklet for CSS selector generation and discovery on complicated sites, and the project's README describes that job as a breeze in one short sentence. Because it is a bookmarklet and not a browser extension, there is no installation step in the usual sense. The README simply sends readers to http://www.selectorgadget.com to try it out, and it does not document a browser store listing, a package manager entry, or a distributed build of your own. That shape suits one-off work: you land on a page that fights your stylesheet, you click the element, and you get a selector you can paste into a test or a rule. The same thin packaging story becomes a liability when you want to depend on it, because there is no stated browser support matrix, no version pinning and no documented upgrade path. It is a tool you invoke, not a component you vendor.

CoffeeScript, jQuery and diff-match-patch in the dependency list

The README has a Technologies section, and it names three things: CoffeeScript, jQuery and diff-match-patch. The local development notes add the detail that guard watches and regenerates the .coffee and .scss files, which tells you the bookmarklet itself is authored in CoffeeScript and its styling lives in SCSS. jQuery is visible in practice through the jQuerySG alias, described in the interface example as SelectorGadget's jQuery alias, so the tool is expected to be used alongside a jQuery page rather than instead of one. diff-match-patch appears in the list without any stated role, and the README does not explain where it enters the selector output. The repository layout is broader than the README implies: besides build/, chrome/, chrome_listing/, doc/, lib/, spec/ and vendor/, there is a .devcontainer/ directory, a Gemfile, a Gemfile.lock, a Guardfile and a .ruby-version. Someone maintaining this would be working in a Ruby flavoured toolchain, not in a single script.

The remote interface replaces the standard display and controls

The most interesting part of the project is not the selector output but the hook the README calls a remote interface, a mode where the standard display and controls are replaced by a JavaScript file of your own. The example starts by grabbing the global instance and building an input field that it appends to the interface container:

// sg_interface.js

var SG = window.selector_gadget

// Add field to display current selection (note the use of jQuerySG, 
// SelectorGadget's jQuery alias).
var path = jQuerySG('<input>', { id: 'sg-status', class: 'selectorgadget_ignore' })
SG.sg_div.append(path)
SG.path_output_field = path.get(0)

The same example shows the other half of the contract, a control that tears the interface down cleanly. The button carries the class selectorgadget_ignore, which is how your own markup tells the tool to leave that element alone, and the click handler unbinds both the tool and its container before removing the interface and dropping the global reference. Unbinding is the detail that matters, because a bookmarklet lives in the page, and a tool that forgets to detach its handlers leaves dead handlers attached to the DOM of a site you did not own.

// Add button to dismiss SelectorGadget
var btnOk = jQuerySG('<button>', { id: 'sg-ok', class: 'selectorgadget_ignore' }).text('OK')
SG.sg_div.append(btnOk)
jQuerySG(btnOk).bind('click', function(event) {
  jQuerySG(SG).unbind()
  jQuerySG(SG.sg_div).unbind()
  SG.unbindAndRemoveInterface()
  SG = null
})

Watching the generated path while the selection changes

Because the remote interface can read the current path, it can act as a live monitor rather than a static readout. The README's example polls the input every 50 milliseconds and logs the number of elements the current path matches, which is a quick way to see whether a selector is unique before you keep it. The same wiring also lets a custom interface record selections or push them somewhere else, and the point of a remote interface is that the file is yours, so the shape of that output is entirely your decision. Nothing in the README constrains what you do with the value once you have it, and nothing warns you about a polling loop you leave running in a long lived tab.

var val = saved = path.val()
var tid = setInterval(function() {
  val = path.val()
  if(saved != val) {
    console.log('New path', val, 'matching', (jQuerySG(val).length), 'element(s)')
    saved = val
  }
}, 50)

The remote interface path is set before instantiation

The interface file is not discovered at runtime by scanning the page. It is named in the sg_options object, and that object has to exist before the tool is constructed, which is the only ordering constraint the README states. A one line path is enough, so the interface can live on your own host or inside the repository you are working in:

window.sg_options = {
  remote_interface: '/path/to/sg_interface.js'
}

window.selector_gadget = new SelectorGadget()
// ...

The path is resolved by the page, so the file has to be reachable from wherever the page is served. The README does not cover hosting, CORS headers or caching for that file, which means a team that wants the custom interface in production has to work those details out on its own.

Building from source with bundle and guard, then running the jasmine specs

Local development is documented in two short steps, both of them Ruby tooling. Installing the development dependencies comes first, and the watch process follows, watching and regenerating the .coffee and .scss files as you edit them. The commands are given in the README as bare words, with no flags and no version numbers:

bundle
guard

Since the commands are that bare, a fresh checkout tells you little about what the toolchain expects, and the .ruby-version file is the only hint about the Ruby release the author was using. Tests run in a browser rather than on a command line, which follows from a project that ships as a bookmarklet. The README names jasmine as the test framework and says to open _spec/SpecRunner.html_ while guard is running. On a Mac the same file opens with a single command. There is also a manual path, a second page that loads a local build of the bookmarklet against a folder of test pages, which is how you check behaviour by clicking rather than by assertion:

open spec/SpecRunner.html
open spec/test_sites/bookmarklet_local.html

Running the suite by opening a file in a browser is workable for a small project, but it gives you no headless integration with continuous integration, and the README does not describe one.

Where a built-in browser picker differs from this bookmarklet

The obvious alternative is the element picker that ships inside browser developer tools. The difference in approach is not accuracy but access. A built-in picker gives you a selector in a panel you cannot replace, and it offers no supported hook for a page to swap that panel for something else. SelectorGadget exposes a global instance, an options object and a documented remote interface, so a page can be handed a control surface that fits a specific workflow, such as a field that feeds a live match count into a search box. The cost is that the extension point is a file you host and load, which is more work than clicking a built-in icon, and the README gives no guidance on hosting, caching or cross origin access for that file. Teams that only need a selector for a single page are unlikely to need the difference.

No releases, a thin README, and a jQuery era stack

Two facts limit how much you should lean on this project. The repository publishes no GitHub releases, so there is no version to pin and no upgrade path other than taking whatever the site serves. The last push was on 2026-05-14, and the repository is not marked archived, so the code is still there and still readable, but there is no release cadence to plan around and no upstream that publishes responses to issues. The second limit is dependency age: the project is written in CoffeeScript against jQuery, and the jQuery alias in the public interface means your custom code and the tool share one global assumption about what is on the page. A page that removed jQuery, or that loads a different major version, is exactly the kind of complicated site where you might reach for a selector tool in the first place. The licence is MIT, which permits use, modification and redistribution with the notice preserved, and the repository includes a LICENSE file, but MIT obligations do not extend to the availability of the tool or to any support commitment.

Editorial conclusion

SelectorGadget fits teams that need a quick, scriptable selector for a single stubborn page and can live with an unpinned bookmarklet, a README that stops at the entry point, and a jQuery and CoffeeScript stack. It is a poor fit for a long-lived test suite that needs versioned releases, a documented support matrix, or a maintained upstream. Before adopting it, check three things in your own repository: that the page you care about survives a click-driven selector without a unique id, that your grading rules accept the selectors the tool produces on your target markup, and that you can host a JavaScript file yourself if you plan to use the remote interface, since the README gives no hosting instructions.

Frequently asked questions

Official sources

1. cantino/selectorgadget on GitHub
2. Issues
3. License: MIT
4. Project website
5. README