Suggest Box

Warning: The UI service was deprecated on December 11, 2014. To create user interfaces, use the HTML service instead.

New Version

This library provides one single method to create a SuggestBox in UiApp.


  1. In the script editor, click on Resources > Manage librairies

  2. A popup box opens. Insert the following project key in the textbox: MF97sIdfhAOMooApuDTLVQ-VJ5jnXUK_T and click on the Select button next to it.

  3. Click on the box listing the different versions of the library. Select the latest version available.

  4. Click OK. You can now use this library.


The code below fetch all your contacts and create a UiApp with a SuggestBox to select multiple contacts.

function doGet() {
  // Get a list of all my Contacts
  var contacts = ContactsApp.getContacts();
  var list = [];
  for(var i = 0; i < contacts.length; i++){
    var emails = contacts[i].getEmails();
    if(emails[0] != undefined){
  var app = UiApp.createApplication();
  var suggestBox = SuggestBoxCreator.createSuggestBox(app, 'contactPicker', 200, list);
  return app;


createSuggestBox(UiInstance app, String id, String width, Array list, String optText, Boolean isWritable, Boolean allowMultiSelect)
Creates a new SuggestBox.

Name Type Description
app UiInstance the active UiInstance
id String the id of this SuggestBox
width String the width of this SuggestBox
list Array the set of selections that should match the user's input
optText String Set the display text of this SuggestBox
isWritable Boolean if this is set to false, the text in this SuggestBox is read only and can't be edited. The default is true.
allowMultiSelect Boolean if this is set to false, only one value can be selected. The default is true.

Return Values:

Type Description
SuggestBox the new SuggestBox

Old Version

In this example we are going to make dictionary with a suggest type, "instant" selection like what you would see when using the a Google search box. 

First we will need a database of values (words) to search and the associated meaning (a definition). 
To keep this simple we will use a spreadsheet where column A are words and column B the definition. 

Go ahead and give it a try, type a "c", without the quotes, in the box below. As you type more letters in a specific word the selection narrows. For example: "clac" will shorten the list to just one word that matches. 
Note: There are only a few words in this example and the list is further down the page. 

Here is the best part, click on one of the words that pop up as you type. 
The list is replaced by the definition.   

Now try typing "ime". You will see the same narrowing behavior but now the words dime and grime are returned for selection. 

Word list:


function doGet(){

  var ss = SpreadsheetApp.openById('YOUR_ID');            
  var app = UiApp.createApplication().setTitle('Suggest');
  var grid = app.createGrid(2,1).setId('grid');
  var searchBox = app.createTextBox().setName('searchBox').setId('searchBox');
  grid.setWidget(0, 0, searchBox);
  var listHandler = app.createServerKeyHandler('findStuff')
  return app;

function findStuff(e){
  var ss = SpreadsheetApp.openById('YOUR_ID').getSheets()[0];            
  var cells = ss.getRange(1,1,ss.getLastRow(),2).getValues().findCells(e.parameter.searchBox);
  var app = UiApp.getActiveApplication();
  var table = app.createFlexTable();
  app.getElementById('grid').setWidget(1,0, table);
  for (i = 0; i < cells.length; i++){
    var label = app.createLabel(cells[i][0])
        .setId(cells[i][0]+': '+cells[i][1])
    table.setWidget(i, 0, label);

  return app;

function showSelect(e){
  var app = UiApp.getActiveApplication();  
  var result = app.createLabel(e.parameter.source);
  app.getElementById('grid').setWidget(1,0, result);
  return app;

//extends Object 
//.findCells(String) or .findCells(Number) 
//reterns array[[number(row),number(column)]] 
Object.prototype.findCells = function(key) {   
  var searchMatch = [];
    for (j = 0; j < this.length; j++){
      if (this[j][0].toString().toLowerCase().search(key.toString().toLowerCase()) != -1){
  return searchMatch;