Create ROR-powered typeahead widgets

If your system includes fields that users enter affiliation information into, you can standardize that input and capture corresponding ROR IDs by adding a typeahead widget that prompts users to select an organization from ROR.


ROR Widget tips

  • Use a ROR-powered typeahead to capture the “top level” organization (ex: University of Wisconsin-Madison); department, college or other sub-unit should be captured in a separate text field
  • In addition to the organization name, display other ROR record fields such as city and country, to help users select the correct organization
  • Provide an option to enter the organization name as a text string if no appropriate option available from ROR
  • After a user chooses an organization from the list, don't allow them to edit the name, as this will likely result in incorrectly matched ROR IDs. Instead prompt them to choose a new organization from the ROR list or enter their own.
  • Consider filtering the list of organizations displayed to the user based on context, such as the user's location (browser geolocation, location info entered in other fields on the same form), email domain, and/or organization type.
  • Consider allowing users to provide multiple affiliations, in case of multiple concurrent appointments
  • Consider populating other fields in your form automatically, using data from the ROR record of the organization selected by the user. See the list of ROR record fields in ROR data structure

Populate widgets using the ROR API

A simple way to populate a typeahead widget is to query the ROR API in real-time, as the user types. While this approach has the advantage of being easy to implement, it comes with some disadvantages:

  • Slower/more variable response time vs querying data stored locally
  • Depends on being able to reach the ROR API


Which API search approach should I use in my widget?

The ROR API offers multiple search approaches: query parameter, affiliation parameter and advanced search. For typeahead widgets, we recommend using query parameter search, as it's the quickest and most responsive approach.

Steps to implement a widget using the ROR API include:

1. Send user input to the ROR API
As the user types their affiliation, send the input to the ROR API. We recommend using query parameter search, as it's the quickest and most responsive approach.

2. Parse results
Results are ordered based on matching score, so the most relevant results will appear at the beginning of the result set. Responses are paginated; a maximum of 20 results are returned on the first page. Searches may return many results, so it's not typically useful to retrieve the entire result set.

3. Display results
Display the top results to the user. In addition to the name, include information from ROR like city, country and/or type to help the user choose the correct result.

4. Store selected result
Store the ROR ID for the selected result in your system, along with any other required information.


Code examples coming soon!

Populate widgets using the ROR data dump

Typeahead widgets of all kinds perform better when querying data stored locally vs making requests to external resources. For best performance, we recommend using a local copy of ROR data to build your widget.

Possible approaches include:

  • Use a static copy of the ROR data dump JSON, along with a suggestion engine, such as Bloodhound, a suggestion engine for typeahead.js. See Data dump for information about downloading the latest file.
  • Run your own instance of ROR. This may sound extreme, but in reality the ROR registry/API is a simple application, because it's based on the exact same static JSON file released in the public data dump. There's no database, and changes are only released to the production ROR instance when a new data dump is created. This Python + Elasticsearch application containerized with Docker and available in Dockerhub ror-community/ror-api. More documentation about this approach is comsing soon. In the meantime, see developer setup documentation.
  • Create your own organization data store and search index using ROR record data. This is the most complicated, but most flexible/customizable approach. This is a good fit for large/complex applications with heavy usage and unique needs. This is also a good choice for those combining ROR with other organization data already in their system(s).


Code examples coming soon!