Live Chat

We'll need to share your messages (and your email address if you're logged in) with our live chat provider, Drift. Here's their privacy policy.

If you don't want to do this, you can email us instead at

Search Hints


This library provides a search box that displays results in a list below as queries are typed.

There’s a custom component called SearchHints that you can drag-and-drop onto a Form.

To define the list of possible search results, it has a property called get_keys_function. You should set this to the name of a Server Module function that returns an iterable of results. In the example in the library, the function is simply a search on a Data Tables table:

def get_search_keys():
  """Get the keys to populate the Search Hints."""

When a result is selected, the SearchHints component raises an event called x-search-hints-result. Set an event handler on this event to dictate what happens when the result is selected. The first argument to the event handler is the selected result, as a string.

In the demo, we set up an event that changes a label’s text to display the selected result:

    self.search_hints_1.set_event_handler('x-search-hints-result', self.update_result_label)

  def update_result_label(self, result, **event_args):
    """Set the result label on this Form to the selected search result."""
    self.label_result.text = result

The Search Hints library is completely free to use, so click on the clone link and use it in your app!


You can use it from another app by using the App Dependencies dialog.

When you clone the library, you will also get an example app that shows you how to include it and make use of it.

How it works

The SearchHints component is made from a TextBox and a RepeatingPanel.

The RepeatingPanel’s items are kept up-to-date by the populate_results method. This matches the current query against self.search_keys, or just makes items empty if the query is '' (an empty string).

The TextBox’s focus and change events both call populate_results, so the results panel is updated whenever the user types in the TextBox or clicks on it. The focus event also runs the Server Module function to get the search keys - so if the underlying data changes, the page stays up-to-date.

When a result is selected, the set_result method is called. This simply raises an event called x-search-hints-result on the SearchHints instance, passing the result as a string. Anything that has access to this SearchHints instance can bind event handlers to this event.

Each result is displayed as an instance of SearchHintsResult (SearchHintsResult is the item template of the RepeatingPanel). SearchHintsResult contains a link whose text is one of the matches to the search query. When the link is clicked, it tells its parent SearchHints object to run set_result (via a custom event, x-result-selected).