Flow builder basics

A flow is an interactive guided experience that leads users through specific paths in an application to help them learn features, complete tasks, or navigate processes.

A flow consists of a sequence of steps that can include tooltips, speech bubbles, and modals that appear on specific pages or elements within an application. These steps can be configured with various triggers and actions to create personalized, context-aware guidance that responds to user interactions.

Flows are intended to be both dismissible and completable, and they may feature elements such as backdrops to enhance user focus, tailored positioning, and conditional logic activated by triggers. They serve as a tool for user onboarding, feature adoption, and providing in-app guidance at the right moment.

This guide will help you understand how to use flows effectively.

Popular use cases

• Onboard new users to shorten the time to value.

• Demonstrate complex concepts or functions to reduce friction and add clarity.

• Pair flows with new feature announcements to drive product adoption.

• Drive users to that "Aha!" moment faster by highlighting product value.

Best practices

Prerequisites

You must install userflow.js to fully implement Userflow Flows.

Create a flow

Before you get started, think about who your target audience is, what the flow should help them know or do, and when they should be presented with the flow. Preparing these simple guidelines will help you focus the flow’s direction, content, and outcome.

1. Select Flows in the sidebar.

2. Click Create flow.

3. Select Start from scratch.

4. Enter a flow name and click Create.

Options for starting a flow

A flow can start automatically based on specific conditions, or you can allow a user to start a flow through an action, such as clicking a button or link.

See the Starting flows/checklists guide to learn more.

Select a step type

Each time you add a step, you will be required to select a step type. Additionally, you will add one or more blocks for each step that define the conditions that must be met to proceed to a subsequent step or dismiss/complete a flow.

Step types

Speech bubble: Appears in the lower left corner of your app.
 

Tooltip: Anchors tips and prompts to elements within your app.
 

Modal: Message that appears on top of your app’s main content, temporarily disabling interaction with the underlying page until it’s closed.
 

Hidden: Hidden steps are often used to pause the Userflow UI elements from appearing until a user has completed a previous step. See Hidden steps to learn more.

Speech bubble

Speech bubbles are great for starting a flow with a conversational, action-oriented tone. You can personalize its appearance with different branding and images using themes.

1. Click the gear icon to select and configure Speech bubble as the step type (if it is not already selected).

2. In the configuration panel on the right, toggle Explicit completion step on if the step is one that should mark the flow complete. If not selected, the last step in the flow will automatically be considered a completion step.

3. Toggle Add modal backdrop on if you want to add a semi-transparent layer on top of your app, which adds emphasis to the speech bubble.

4. Edit the pixel width of the speech bubble, if desired. (Default is set to 300px.)

5. Edit the theme selection for the step. Otherwise, it will inherit the flow applied to the theme.

6. Enter text in the speech bubble.
   Tip: Level up your messaging with Userflow’s AI Rephrase option! (Beta available to Pro customers.) Click AI Refresh  in the toolbar to configure the length, tone, and add custom instructions if desired. See AI Rephrase to learn more.
    

7. (Optional) In the formatting bar of the bubble, click + to add interactive elements to the speech bubble, including buttons, survey questions, images, and other attributes. See Adding elements to text to learn more.
   

8. Add a step name at the top of the column to identify the step.

Tooltip

Tooltips are great for guiding users through steps and processes. Keep them brief and action-oriented.

1. Click the gear to select Tooltip as the step type in the configuration panel on the right.

2. Toggle Explicit completion step on if the step is one that should mark the flow complete. If not selected, the last step in the flow will automatically be considered a completion step.

3. Edit the pixel width of the tooltip, if desired. (Default is set to 300px.)

4. Edit the theme selection for the step. Otherwise, it will inherit the flow applied to the theme.

5. Enter the text in the tooltip.
   Tip: Keep messaging actionable and friendly in1-2 short sentences (under 200 total characters).

6. Click Show tooltip on this element, then select and configure the element in your app to which the tooltip should be anchored. See the Tooltip element selection and configuration section below for additional instructions.
    

Modal

Modals are great for one-step announcements, prompting a user to start a flow or end a flow with a congratulatory message after completing it. Add confetti to a modal at the end of a flow to celebrate each user’s success.

1. Click the gear to select Modal as the step type in the configuration panel on the right.

2. Toggle Explicit completion step on if the step is one that should mark the flow complete. If not selected, the last step in the flow will automatically be considered a completion step.

3. Edit the pixel width of the modal, if desired. (Default is set to 600px.)

4. Edit the theme selection for the step. Otherwise, it will inherit the flow applied to the theme.

5. Enter text in the modal.

Hidden

Hidden steps can provide a user interaction that leads to subsequent steps in a flow, without showing a visible Userflow interface for that step. While a hidden step is active, the flow session remains active in Userflow, allowing users to interact before proceeding to the next step or determining which step to take based on their response.

Examples:

• If the previous step asked the user to perform an action in your app, and you want to wait for them to complete that action without a Userflow UI overlay.

• Automatically navigate users to a specific page without requiring them to click anything; a hidden step can create a seamless transition.

• If you have different paths a user can take based on their response, hidden steps can lead them to different subsequent steps based on their response to a previous step.

⚠️ Warning

Hidden steps must have at least one trigger whose condition eventually matches, and it must have an action that either goes to a non-hidden step, starts another flow, or dismisses the flow.

If a trigger never activates (or takes too long to activate), the user could get stuck in a hidden step indefinitely. While the user won’t see any Userflow UI elements, the flow session remains active in Userflow and will block other content (flows, checklists, launchers) from appearing.

We recommend avoiding using hidden steps unless

See Hidden steps to learn more.

Tooltip element selection and configuration

Once you add a tooltip step, you must select the element in your app to which you want to anchor the tooltip.

Element selection

Automatic element selector

One of Userflow's key strengths is its user-friendly and robust automatic element selector. Instead of displaying raw CSS, it shows an image of your selected element and uses multiple data points to ensure reliable element selection.

Advanced options include:

• Dynamic text - Allows Userflow to find target elements even when text changes for each user

• Strictness - Lets you adjust how strictly Userflow should identify the correct element (Loose or Strict)

Manual Element Selection

While we recommend using the automatic selector, you can also select elements manually by clicking Go Manual. This allows you to find elements based on either text or CSS data.

Element Not Found

If Userflow cannot find a selected element, it may be due to a conflict with an iframe, multiple elements sharing the same CSS ID, or an element in your app taking too long to load, which causes the flow to time out. See Element not found to learn how to select an element when it is not found.

Tooltip Positioning

To control tooltip position (left, right, above, or below the target element):

1. Click on the selected element in the flow step builder

2. Select Specify tooltip position

Note: Tooltips require sufficient UI space and may display in alternative positions if the specified position lacks adequate space.

Creating Advanced Flows

Step Triggers

Use Triggers to create "if this, then that" rules to navigate steps or perform actions based on various conditions. This allows for more robust and sophisticated flows. You can add multiple triggers to a single step for branching flows, skipping steps, and more.

To add a trigger, click Add block > Trigger. Trigger conditions include:

• Attribute - Trigger based on specific user attributes

• Current page (URL) - Trigger when the user reaches a certain page

• Element is present/clicked/disabled - Trigger based on UI element state (great for handling long load times)

• Text input value - Trigger when an input field contains a specific value

• User fills in input - Trigger when a user fills in an input field with any value

• Current time - Trigger at specific times or during time periods

• Water is wet - Always true condition (triggers regardless of other factors)

• Logic group - and, or logic

• Wait - Add the number of seconds before continuing

Best Practice: Add triggers to non-hidden steps to prevent users from getting stuck.

Note: Custom event conditions aren't currently supported in triggers. As a workaround, update a user attribute instead of sending an event.

Apply actions to step triggers

For each flow step, you can add buttons, tooltip targets, and step triggers.

When these elements are activated, you can specify actions to occur:

1. Go to step - Navigate to a specified flow step

2. Dismiss - End the current flow

3. Start new flow/checklist - Begin a different flow/checklist (auto-dismisses the current flow)

4. Navigate to page - Direct users to a specific URL (same tab or new tab)

5. Snooze flow - Pause the flow for a specified duration (Learn more)

6. Set user attribute - Define attribute values (can include incrementing numeric values)

7. Evaluate javascript - Execute JavaScript code to trigger actions in your application

Flow Management

Temporarily Hiding Flows

To display flows only on certain pages after they've started, enable Temporarily hide flow if in the flow's advanced settings. This conceals the flow when conditions are met and allows other flows to start.

Important: Always use auto-start conditions to control who sees a flow and when, rather than relying on the temporary hide condition.

Using Backdrops

Backdrops provide a powerful way to focus user attention by adding a semi-transparent layer over your application. This layer covers everything except Userflow content and tooltip target elements, blocking clicks on background elements to guide user actions.

• Modal steps include backdrops by default

• For tooltip and speech bubble steps, you can toggle backdrops on per step

• Backdrop behavior and appearance can be adjusted in theme settings

Ending Flows

Dismissing a Flow

Users can dismiss flows at any time via the X-button in the top corner of modals, speech bubbles, and tooltips. While you can disable this button in advanced settings, we generally don't recommend it.

You can also add Dismiss actions to buttons, tooltip target clicks, survey questions, and step triggers.

Best Practice: Always add a dismiss action on the last step to provide a clear call-to-action.

Note: When using Start a flow actions, the current flow automatically dismisses. Other actions like, Navigate to page require explicit dismiss actions.

Important: Ensure flows eventually dismiss or hide to prevent blocking other flows from starting.

Completing a Flow

Flow completion differs from dismissal. A flow is considered complete when users reach a completion step. By default, the last step is the completion step, but you can designate any step as an Explicit completion step in the builder.

For conditional completion:

• If you want a flow to complete only when users click a specific button, add a hidden step after that button

• Configure this hidden step with an "always true" trigger (Water is wet) and a dismiss action

Customizing X-Button Behavior

By default, clicking the X-button dismisses a flow or checklist. You can modify this behavior in theme settings to display an exit menu with options to resume, close (dismiss), or restart the flow.

Note: This exit menu appears only on steps beyond the first step.

Adding confetti feedback

Do you want to add some delight to your onboarding tours? Try adding confetti!

Driving engagement and enthusiasm in your flows depends on keeping the user’s interest and providing feedback and rewards. Help your users celebrate their successes with a fun confetti animation.

Confetti can be added to new and existing modals, tooltips, and speech bubbles in any flow. To add confetti, use the toggle switch to activate the Add confetti option.

A visual depiction of confetti will appear behind the modal, tooltip, or speech bubble in the builder to indicate that it is on for that step.