Skip to main content

Retool Mobile quickstart

Learn about the fundamental concepts of Retool Mobile.

This guide serves as an introduction to Retool mobile apps. It covers many of the concepts and terminology you would come across as you build mobile apps. After reading this page, you should have a good understanding of the fundamentals for building Retool mobile apps.

Introduction​

A Retool Mobile app is a mobile application that interacts with your data sources. You assemble the user interface using components, such as input fields and tables. Mobile apps also use the concept of screens to create multiple views—similar to pages, such as display a list of contacts and then selecting one for which to view details. You also write code that interacts with data, transforms values, control behavior, and more.

Mobile apps run natively on iOS and Android using the Retool Mobile app.

Retool officially supports the latest stable releases of the following desktop web browsers:

Editing apps in alternative browsers, on mobile devices, or using beta and nightly builds is not officially supported.

Mobile app UI​

The user interface of a mobile app is made up of components and screens.

Components​

These are interface elements, such as a text input field, with which users interact. Components are objects with internal state. Retool exposes properties, methods, and events with which you can interact.

Property values change as you configure or interact with components. For example, the List Collection component's selectedItem property changes whenever a user selects an item from the list.

Screens​

Screens group components together into distinct views, similar to application windows. Users navigate between screens using the tab bar or by interactions that trigger event handlers, such as pressing a button or selecting an item from a list.

Screens also function as modals and sheets, providing a number of ways for which users can interact.

Demo

Assemble components and screens​

You build mobile apps using the App IDE for Retool Mobile, Retool's drag-and-drop app building web interface. You use the App IDE to:

  • Visually assemble the mobile app interface.
  • Write queries to interact with data.
  • Configure actions based on user interactions.
  • Share apps directly with users.

Connect components together​

Most component properties are editable. You configure them in the IDE with either static values (string, number, boolean, array, and object) or reference other component values using {{ }} embedded expressions, similar to the use of template literals.

You reference property values using dot notation. For instance, you can select an item from the inventory list to get more details. The Image component value is set to {{ itemCollection.selectedItem.image }}, which updates whenever you change the selection.

SQL query to retrieve records from a database table.

Use JavaScript expressions for values​

Retool performs string interpolation and evaluates {{ }} embedded expressions as JavaScript. As a result, you can write JavaScript code—that evaluates and returns a value synchronously—almost anywhere. This enables you to dynamically set property values using transformations or conditional logic to build complex apps.

The List Collection component uses a ternary operator and the selected value of the Segmented Control mobile component to toggle sorting the list by quantity or price.

{{ 
  sortOptions.value === 'quantity' 
  ? getItems.data.sort((a, b) => b.quantity - a.quantity) 
  : getItems.data.sort((a, b) => b.price - a.price) 
}}
Conditional logic changes the sort order of the list dynamically.

Connect your data using resources​

A resource is a saved set of user-configured properties that determines how Retool connects to a data source, such as a PostgreSQL database or REST API. You create a resource for each data source you want to use with Retool, then write queries to interact with them.

Each resource has configuration options that Retool uses when interacting with a data source. This simplifies how you query data sources while ensuring access is secure.

When a resource query is run, Retool proxies the request to the data source, server-side, using the resource's configuration settings. This means only Retool directly connects to a data source, not your users.

Read and write data using queries​

A query is a piece of code you write to interact with a resource and perform CRUD operations. As with components, queries maintain an internal state and expose properties. Queries can also perform asynchronous actions and run simultaneously with other queries.

Queries are not part of an app's user interface. You reference the query's data property to read and display data in components for which users can interact. Queries can also reference component input values and write them back to the data source.

SQL query to retrieve records from a database table.

Connect components and queries together for dynamic interfaces​

Under the hood, Retool maintains a dependency graph for each app. This represents all property values and where they're referenced. Whenever a property changes, all downstream references using embedded expressions automatically update. This is similar to how spreadsheet formulas work when referencing cell values; if a referenced value changes then the formula instantly updates its result.

You can chain embedded expressions together by referencing values that also use embedded expressions. Any input value changes automatically propagate through the entire app. This makes it possible to build powerful applications with very few lines of code.

The dependency graph enables Retool to prevent you from creating circular dependencies, where two or more properties rely on each other to function. If you attempt to reference values that rely on one another, the IDE displays a warning.

A circular dependency warning.

The Inventory mobile app contains a List Collection component to display a list of inventory items. Its data source is set to getItems.data. There is also a slider that filter results based on quantity. This is done using a JavaScript filter() expression that transform the output of the query.

return formatDataAsArray(data).filter(row => row.quantity <= {{quantitySlider.value }})
The query data dynamically transforms as the slider value changes.

Control and run queries with event handlers​

You configure event handlers to perform actions whenever a specific event occurs, such as a button press or query error. There are numerous actions available, such as setting component values and triggering queries.

The Inventory mobile app uses a number of different event handlers. For instance, an event handler is configured to navigate to the itemDetailsScreen screen when an item is selected from the list. This screen contains components that reference the selected item's properties.

The query data dynamically transforms as the slider value changes.

Transform data using JavaScript transformers​

While you can use JavaScript within {{ }} embedded expressions, you may need to manipulate multiple sources of data and implement complex logic to produce values, such as filtering or joining data sets.

A JavaScript transformer is a reusable block of JavaScript. Unlike the data transformation you can perform directly from a query, transformers operate independently. You reference property values using embedded expressions and the results of the transformation are output on the transformer's value property using a return statement.

The Inventory mobile app uses a transformer, totalPrice, to calculate the total amount of all visible items. The result is then formatted using toLocaleString() and displayed in a Text mobile component.

const items = {{ getItems.data }}
const total = items.reduce((acc, item) => acc + (item.price * item.quantity), 0);

const formattedTotal = total.toLocaleString('en-US', {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2
});

return formattedTotal;
Using a transformer to calculate the total amount of inventory items.

Transformers are maintained by the dependency graph and continually output a transformed value. If you make changes to any values in the dependency chain, the transformer automatically updates.

Script apps with JavaScript​

You can write JavaScript code to control app behavior, set property values, and more. Components and queries are globally scoped and include built-in methods to control their state. These methods can accept supported parameters, such as string or index values. In either case, you only need to use standard JavaScript notation, not {{ }} embedded expressions.

JavaScript queries can output data using a return statement.

The Reset button below the list triggers a JavaScript query that sets the value of the Slider and Segmented Control mobile components, effectively resetting the results to their defaults.

quantitySlider.setValue(50);
sortOptions.setValue('quantity');
Set the value of components using a JavaScript query.

Run apps natively on iOS and Android​

You can run mobile apps in the browser as progressive web apps.

Users browse and run mobile apps natively using the Retool Mobile app iOS and Android. This approach simplifies deployment and makes all Retool Mobile apps instantly available. You can share links to apps so users can launch them on their device, or open them in a browser.

Browse and launch apps

The Retool Mobile app for iOS and Android uses React Native to run mobile apps natively. Users can log in to their Retool organization, browse or search for mobile apps, and launch them on their mobile device.

Whenever you add or update an app, it's immediately available within the Retool Mobile app for users.

Leverage mobile device functionality​

Retool Mobile enables you to make use of software and hardware functionality of mobile devices.

  • Biometric verification. Use built-in biometric features to provide an extra layer of identity verification, such as fingerprint or face scanning. After users log in, they are prompted to verify their identity using biometrics each time they bring the app to the foreground. Biometric verification does not replace your existing login mechanisms.
  • NFC: Use a device's built-in NFC reader to capture data from NDEF-formatted tags.
  • Camera: Use the camera to take photos and scan barcodes.
  • Zebra: Receive data captured by a Zebra Android device with dedicated hardware.

Send push notifications​

The Retool Mobile app includes support for push notifications. You can trigger notifications with queries using the built-in Mobile Push Notifications resource from any app or workflow.

Configuring push notifications is a two-part process:

  • Add a query to mobile apps that subscribe users to push notifications and enables them on their device.
  • Write queries in Retool apps and workflows to send push notifications to subscribed users.

Push notifications use topics to represent the scope for recipients. Topics are similar in function to mailing lists—users subscribe to them based on what information they want to be notified about. Users subscribe to push notifications using a subscription query in which you specify the topics to use. To send a notification, you use a query that references the relevant topic rather than managing a separate list of users.

Work offline​

Offline mode allows natively run mobile apps to continue functioning without a data connection. When enabled, queries that read data can cache the most recent results to make them available offline. Queries that write data are held in a queue and run once the data connection is restored.

Wrap up​

Using these fundamental concepts, you can build complex mobile apps that:

  • Contain polished user interfaces that can adapt to your needs.
  • Dynamically reference values anywhere using dependency chains.
  • Connect with almost any API and database to interact with your data.
  • Perform actions using conditional logic in response to user events or script apps to control behavior.

Next steps​

You now have a basic understanding of how to build a Retool app. Check out the mobile app tutorial to build a complete app from start to finish.