[whatwg] SearchBox API

Tony Gentilcore tonyg at chromium.org
Wed Oct 13 15:59:33 PDT 2010

Hi All,

We're adding instant search integration [1] to Google Chrome, allowing
the search provider to communicate suggestions to the user agent.

If there is interest, we'd like to make sure that we do this in such a
way that any search provider or user agent can implement it.

While the search boxes in most user agents support suggestions via an
HTTP API, instant requires a DOM API. We propose exposing a
window.navigator.searchBox object. There is some precedence for this
with window.navigator.registerProtocolHandler()/registerContentHandler()

Is this something that others are interested in? If so, any feedback
on our working API [3]?


[1] http://googlesystem.blogspot.com/2010/09/instant-search-in-google-chrome.html
[2] http://dev.w3.org/html5/spec/Overview.html#navigator

interface SearchBox {
 // Search query and cursor position.
 readonly attribute DOMString value;
 readonly attribute unsigned long selectionStart;
 readonly attribute unsigned long selectionEnd;

 // Dimensions of the portion of the search box (e.g. a dropdown)
 // that overlaps the window.
 readonly attribute unsigned long x;
 readonly attribute unsigned long y;
 readonly attribute unsigned long width;
 readonly attribute unsigned long height;

 // Set ordered suggestions. Valid for current this.value.
 void setSuggestions(in DOMStringArray suggestions);

 // Notification that the user has changed the input value.
          attribute Function onchange;

 // Notification that the user has committed input (e.g. pressed enter).
          attribute Function onsubmit;

 // Notification that the user has selected a suggestion (e.g. down
arrow to suggestion).
          attribute Function onselect;

 // Notification that the user has cancelled input (e.g. closed dropdown).
          attribute Function oncancel;

 // Notification that the dimensions of the overlapping region have changed.
          attribute Function onresize;

interface NavigatorAbilities {
 // Raises permission denied if page isn't default search provider.
 readonly attribute SearchBox searchBox;

// Example usage.
var searchBox = window.navigator.searchBox;
searchBox.onchange = function() {
  if (this.selectionStart == this.selectionEnd &&
      this.selectionStart == this.value.length)
    alert('Cursor is at end of input');

  alert('Setting suggestions for: ' + this.value);
  this.setSuggestions(["one", "two"]);
searchBox.onsubmit = function() {
  alert('User searched for: ' + this.value);
searchBox.onselect = function() {
  alert('User selected suggestion: ' + this.value);
searchBox.oncancel = function() {
  alert('Query when user cancelled: ' + this.value);
searchBox.onresize = function() {
  alert('Resized to: ' +

More information about the whatwg mailing list