​
Overview

Simple flows are focused, step-by-step guided tours that walk users through specific features or tasks in your application.

Unlike comprehensive onboarding flows, simple flows tackle one specific goal—like creating a project, setting up a profile, or understanding a dashboard. They provide contextual guidance right when and where users need it.

​
When to use simple flows

  • For new features: Introduce users to functionality they haven’t used before. Instead of hoping users discover new features, proactively show them how to use them.
  • For complex processes: Guide users through multi-step workflows that might otherwise cause confusion. This reduces friction and increases completion rates for important tasks.
  • For converting free users: Highlight premium functionality to free users with targeted tours. Show them what they’re missing to encourage upgrades.
  • For contextual help: Provide in-app assistance for specific tasks when users request it. This reduces support tickets and increases user confidence.

​
How simple flows work

When a simple flow is triggered, it guides users through a series of steps:

  1. Highlighting: The flow highlights a specific UI element on your page
  2. Instruction: It displays contextual instructions for that element
  3. Action: It waits for the user to complete the specified action (click, input, etc.)
  4. Progression: After the action is completed, it automatically moves to the next step
  5. Completion: When all steps are finished, the flow ends

This creates a guided, interactive experience that ensures users successfully complete each action before moving forward.

​
Simple flow structure

​
1. Flow definition

First, define the flow itself with its basic properties:

const featureTour = {
  id: "feature-tour",          // Unique identifier for your flow
  type: "simple",              // Specifies this is a simple flow
  name: "Feature tour",        // Name of the tour
  description: "Learn how to use our key features" // Optional description
};

The id is particularly important — it’s how you’ll reference this flow when triggering it manually.

​
2. Steps

Steps guide users through the feature. Each step highlights a specific element and provides instructions.

steps: [
  {
    id: "create-project-step",   // Unique identifier for this step
    type: "guided",              // Step type: 'guided' | 'self-paced'
    position: "create-button",   // Element ID to highlight
    content: {
      description: "Click this button to create a project." // Description of the step
    }
	
  }
]

The position value should match the ID of an element in your application. Pointer will find this element and highlight it during the tour.

The type can be either guided or self-paced:

  • Guided steps automatically progress when the user completes the specified action.
  • Self-paced steps give users more control over their progress. They are typically used for documentation-style guides or tips.

Note: When configuring a step, you’ll see more props available. However, those are only used when creating a composite flow. Any other props added when creating a simple flow will not be visible.

​
3. Actions

Actions make your flow interactive, defining what the user needs to do to proceed to the next step.

{
  id: "create-project-step",
  type: "guided",
  position: "create-button",
  content: {
    description: "Click this button to create a new project."
  },
  action: {
    type: "click" // Wait for user to click before proceeding
  }
}

Supported action types are:

  • click — wait for the user to click the highlighted element
  • input — wait for the user to type in a form field

​
Creating page-specific flows

Often, you’ll want flows to appear only on specific pages. You can achieve this by adding a page property:

const profileTour = {
  id: "profile-tour",
  type: "simple",
  name: "Profile setup",
  page: "/profile",          // This flow will only activate on the profile page
  steps: [
    // Steps specific to the profile page
  ]
};

The flow will only activate when the user is on the specified page, ensuring contextual relevance.

​
Creating cross-page flows

Sometimes you need to guide users across multiple pages of your application. This is possible by specifying different pages for individual steps and using navigate actions.

steps: [
  // Step on the dashboard page
  {
    id: "find-profile",
    type: "guided",
    position: "profile-link",
    page: "/dashboard",      // This step appears on the dashboard page
    content: {
      description: "Click here to navigate to your profile settings."
    },
    action: { type: "click" }
  },
  
  // Next step on the profile page
  {
    id: "edit-avatar",
    type: "guided",
    position: "avatar-upload",
    page: "/profile",        // This step appears on the profile page
    content: {
      description: "Upload a profile picture by clicking here."
    },
    action: { type: "click" }
  }
]

Pointer automatically handles the page transitions, waiting for the new page to load before continuing the flow.

Note: for cross-page flows, we recommend setting up a composite flow. Simple flows are ideal for quick, single page flows.

Not all guidance needs to happen within your app. You can create flows that direct users to external resources like documentation. This creates a simple flow with just a button that opens the specified URL. These are only available in composite flows.

​
Triggering simple flows

You can trigger flows using the useFlow hook. Check out the Triggers page for more info.

​
Complete example

Here’s a complete example of a simple flow for introducing users to a dashboard:

const dashboardTour = {
  id: "dashboard-tour",
  type: "simple",
  name: "Dashboard intro",
  page: "/dashboard",
  
  steps: [
    // Show metrics panel
    {
      id: "metrics-step",
      type: "guided",
      position: "metrics-panel",
      content: {
        description: "Here you can see key metrics about your account activity and progress."
      },
      action: { type: "click" }
    },
    // Create a project
    {
      id: "create-project-step",
      type: "guided",
      position: "create-project-button",
      content: {
        description: "Let's create your first project. Click this button to get started."
      },
      action: { type: "click" }
    }
  ]
};

​
Best practices

  • Focus on one goal per flow. Each flow should help users accomplish a specific task.
  • Keep instructions concise. Tell users exactly what to do in as few words as possible.
  • Explain the “why” not just the “what.” Help users understand why each step matters.
  • Test on multiple devices to ensure your flows work well on different screen sizes.
  • Validate user actions to ensure users successfully complete each step before moving forward.
  • Consider keyboard navigation for users who don’t use a mouse.
  • Avoid blocking critical UI elements with your flow tooltips.

​
Next steps

  • Learn about composite flows for comprehensive onboarding experiences
  • Explore triggers to control when flows appear