Skip to main content

Getting started with the Wizard component

Learn how to build a step-by-step interface with multiple paths using the Wizard component.

Classic apps

You're viewing documentation for classic apps, which use Retool's original app editor. The AI app builder is the recommended way to build apps and where Retool focuses new development.

The Wizard component allows you to group components into a series of steps that follow a linear path or branch into multiple ones. It supports running queries on step change or reset, virtual steps that display a loading screen, and setting the initial step dynamically. The Wizard component also includes a workflow editor to add or remove steps and define transitions between them.

This guide walks you through building a wizard to deactivate a user. Before doing so, the wizard checks that the user's account is in good standing. If not, you have the option of sending the user an invoice to collect an outstanding balance. The wizard also requires you to provide a reason before you deactivate the user.

Import user data​

For the purpose of this guide, your classic app uses sample user information stored in Retool Database. To import the data:

  1. Download sample_wizard_users.csv. It contains 25 users with the following columns:

    Column nameDescription
    idThe user's unique ID.
    userThe user's email address.
    activeWhether the user is active (true or false).
    balanceThe user's outstanding balance, from 0 to 10.
    reasonThe reason a user was deactivated. Empty.

  2. Navigate to Resources and select Retool Database.

  3. Click Import CSV and select Into a new table.

  4. Upload sample_wizard_users.csv, name the table wizard_users, and then click Create table.

Query user data​

First, create a new classic app. Retool automatically creates a new query (query1) to get started. Select the query and change its Resource to Retool Database, then write the following SQL statement. Click Save & Run to save the query and run it.

SELECT
  *
FROM
  wizard_users
ORDER BY
  id

The query returns sample data as an object of column arrays, with one array per column:

{
  "id": [1, 2, ...],
  "user": ["amara1@example.com", "mateo2@example.com", ...],
  "active": [true, true, ...],
  "balance": [0, 1, ...],
  "reason": [null, null, ...]
}

Click the query's name and rename it getUsers.

Build the wizard​

Drag a Wizard component onto the Retool canvas. Wizard functions like the Container component and groups other components together. Next, drag a Table component onto the Wizard. The table automatically uses the most recent query as a data source to display the user data.

Right click the table and select Rename. Rename it to selectUser.

Create additional steps​

Select the wizard and click Edit workflow in the Edit section of the right panel to open the Workflow editor. You use this to add additional steps and define paths through the wizard.

Navigate the Workflow editor

You can pan and zoom around the Workflow editor as you build out additional steps.

Rename this first step to Select user and add two new steps for Payment reminder and Deactivate user. Connect Select users to both new steps by holding the Shift key as you click-and-drag.

Define paths​

The wizard can follow different paths depending on truthy conditions. If the path's Enable if value evaluates to true, the wizard presents this as a next step. If it evaluates to false, the step is not available. Set the value of Enable if between Select user and each path of the following:

  1. Send payment reminder: {{ selectUser.selectedRow.balance > 0 }}. This enables the path to the Send payment reminder step only if there's a balance remaining.
  2. Deactivate user: {{ selectUser.selectedRow.balance === 0 }}. This enables the path to the Deactivate user step only if the balance is zero.
Update Enable if conditions in navigation
Update Enable if conditions in navigation

Customize payment reminder step​

Each step of a wizard is independent and can contain different components. Click on the Edit step dropdown in the Edit section of the right panel, then select Payment reminder.

To create a form that can be used to send a payment reminder:

  1. Drag a Form component to the wizard and update its title to Reminder form.
  2. Drag an Email component to the form. Set its value to {{ selectUser.selectedRow.user }}.
  3. Drag a Currency component to the form. Set its value to {{ selectUser.selectedRow.balance }}.

The form automatically uses the email address and the balance as values for the inputs. You could use these fields within a query to send emails using the Retool Email resource. For the purpose of this guide, you won't configure the form to perform any further action.

Customize the deactivation step​

The last step in the wizard is to deactivate the selected user. Select Deactivate user in the Edit step dropdown of the Inspector, then drag a Select component on to the step and rename it to reasonSelect. Update its list of options to include:

ValueLabel
stoppedStopped using service
costToo expensive
otherOther reason
Add Select dropdown to Deactivate user step
Add Select dropdown to Deactivate user step

Configure a virtual step to deactivate user​

You can use a virtual step to automatically trigger a query or conditionally route to a different step. In this case, to deactivate a user and submit the reason.

Create deactivation query​

First, create a new Retool Database query in GUI mode with the following information:

  • Table: wizard_users

  • Action type: Bulk update via primary key

  • Primary key column: id

  • Array of records to update:

    {{ [{ id: selectUser.selectedRow.id, reason: reasonSelect.value, active: false }] }}

Save the query, then rename it to deactivateUser.

This query updates the record that matches the selected user's ID. It includes the reason from the dropdown menu and sets active to false, disabling the user.

Add virtual step​

Add a virtual step to the workflow editor named Reason selected and toggle Virtual step on. Set On enter query to the update query you just created. Next, create a path from the Deactivate user step to this new virtual step. To ensure that a reason is selected, set this path's Enable if to {{ reasonSelect.value !== null }}.

Selecting a reason enables the virtual step. As you progress to it, the virtual step triggers the query and deactivates the user.

Add a final step to verify the changes​

Virtual steps appear as loading screens and automatically progress to another step once a query is run. The final step of this wizard verifies the changes have been made.

Create another Retool Database query in SQL mode that retrieves the deactivated user:

SELECT
  *
FROM
  wizard_users
WHERE
  id = {{ selectUser.selectedRow.id }}

Update the query's name to verifyUser.

Add another step to the wizard and name it Verification. Connect a path from the Reason selected step and set Trigger if to {{ deactivateUser.data }}, so it immediately moves to the next step after triggering the deactivation query.

Add verification step
Add verification step

Select the Verification step and drag a Text component to it. Update its value to display the query's results.

User: {{ verifyUser.data.user[0] }}
Active: {{ verifyUser.data.active[0] }}

Your wizard is now ready and can deactivate users. If a user has an outstanding balance, it presents the option to send a reminder instead.