Build a button-driven onboarding carousel

Overview

This tutorial shows you how to create a multi-step onboarding carousel using a single HTML In-App Message. Unlike traditional carousels that rely on swipe gestures, this approach uses button-driven navigation and keeps all steps within one message. What you’ll build:

A two-step onboarding flow with images, text, and buttons
Button navigation (tap “Next” to advance, tap “Get Started” to dismiss)
Progress indicator dots
Smooth fade transitions between steps

Onboarding carousel showing welcome screen with image, text, and Next button

Use this approach when you want to:

Guide users through a short onboarding or education flow (2-5 steps)
Require users to explicitly tap a button to continue (no swipe gestures)
Keep everything inside one HTML In-App Message for simplicity
Automatically dismiss the message when the flow is complete

This guide uses an HTML In-App Message for full control. You can also build card-based onboarding flows with the drag-and-drop editor—those cards are swipable but offer less customization.

Prerequisites

Before you begin, make sure you have:

An active OneSignal app with In-App Messages enabled
Permission to create or edit HTML In-App Messages
Mobile SDK installed in your mobile app
Basic understanding of HTML, CSS, and JavaScript

How the multi-step flow works

Before diving into the code, it’s important to understand the technical approach. This implementation uses one HTML In-App Message that switches between steps by showing and hiding content, not by loading multiple separate messages. The architecture relies on four core components:

Card containers for each step

Each step is wrapped in a <div> with the card class and a unique ID:

<div id="card-0" class="card active">...</div>
<div id="card-1" class="card">...</div>

All cards exist in the DOM simultaneously
Only one card is visible at a time (controlled by the active class)

CSS visibility control

CSS handles the show/hide logic using opacity and pointer events:

.card {
  opacity: 0;
  pointer-events: none;  /* Prevents interaction with hidden cards */
  transition: opacity .25s ease;
}

.card.active {
  opacity: 1;
  pointer-events: auto;  /* Allows interaction with visible card */
}

Why this matters:

opacity: 0 hides the card visually but keeps it in the layout
pointer-events: none prevents accidental clicks on hidden cards
transition creates smooth fade effects

JavaScript state management

The setActive(i) function controls which card is visible:

function setActive(i) {
  // Update card visibility
  document.getElementById("card-0").className = i === 0 ? "card active" : "card";
  document.getElementById("card-1").className = i === 1 ? "card active" : "card";
  
  // Update progress dots
  var dots = document.getElementById("dots").children;
  dots[0].classList.toggle("active", i === 0);
  dots[1].classList.toggle("active", i === 1);
}

This function:

Removes active from all cards
Adds active to the target card
Updates progress indicator dots

Button event listeners

Buttons trigger navigation or dismissal:

// Advance to next step
document.getElementById("next-0").addEventListener("click", function () {
  setActive(1);
});

// Dismiss the In-App Message
document.getElementById("done").addEventListener("click", function (e) {
  if (window.OneSignalIamApi && OneSignalIamApi.close) {
    OneSignalIamApi.close(e);
  }
});

Important: OneSignalIamApi.close(e) is the OneSignal SDK method that dismisses the In-App Message from within the HTML.

Key insight: This is a single-page application (SPA) pattern within an In-App Message. All content is loaded once, and JavaScript manages state changes without reloading.

Step 1: Create a new HTML In-App Message

In the OneSignal dashboard, go to Messages → In-App Messages
Click New In-App Message
Select HTML as the message type
Choose Full Screen or Large layout (recommended for onboarding to maximize visual impact)
Continue to the HTML editor

The HTML editor preview may not fully reflect runtime behavior. Always test on a real device or test user to verify animations, button behavior, and the dismiss action.

Step 2: Add the HTML template

Replace the editor contents with the template below. This template includes:

Self-contained code: All HTML, CSS, and JavaScript in one file
Button-driven navigation: No swipe gestures (more reliable across devices)
Fade transitions: Smooth opacity changes between steps
OneSignal SDK integration: Uses OneSignalIamApi.close(e) to dismiss the message
Mobile-optimized: Responsive layout with viewport meta tag

View complete HTML template

<!doctype html>
<html>
<head>
  <meta charset="UTF-8" />
  <!-- viewport-fit=cover ensures safe area coverage on notched devices -->
  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
  <style>
    /* Base styles - reset and system font */
    html, body {
      margin: 0;
      padding: 0;
      background: #ffffff;
      font-family: -apple-system, system-ui;
    }

    /* Main container with padding */
    .wrap { 
      padding: 28px 22px 24px; 
    }

    /* Stage container - holds all cards in same position */
    .stage {
      position: relative;
      min-height: 74vh;  /* Ensures enough vertical space */
    }

    /* Card - each step of the onboarding flow */
    .card {
      position: absolute;  /* All cards overlap in same position */
      inset: 0;            /* Full coverage of stage */
      display: flex;
      flex-direction: column;
      align-items: center;
      opacity: 0;               /* Hidden by default */
      pointer-events: none;     /* Prevents clicks when hidden */
      transition: opacity .25s ease;  /* Smooth fade effect */
    }

    /* Active card is visible and interactive */
    .card.active {
      opacity: 1;
      pointer-events: auto;
    }

    /* Typography */
    h1 {
      margin: 44px 0 12px;
      font-size: 26px;
      text-align: center;
    }

    p {
      margin: 0;
      color: #6b7280;
      text-align: center;
      max-width: 260px;
      line-height: 1.35;
    }

    /* Image container - square with rounded corners */
    .image {
      width: 240px;
      height: 240px;
      border-radius: 16px;
      margin: 24px 0 12px;
      background-size: cover;
      background-position: center;
    }

    /* Primary button */
    .btn {
      margin-top: auto;  /* Pushes button to bottom of card */
      width: 100%;
      max-width: 260px;
      height: 52px;
      border: 0;
      border-radius: 12px;
      background: #3b82f6;  /* Blue - customize to match your brand */
      color: #fff;
      font-size: 18px;
      font-weight: 600;
    }

    /* Progress indicator dots */
    .dots {
      display: flex;
      justify-content: center;
      gap: 8px;
      padding: 12px 0 8px;
    }

    .dot {
      width: 8px;
      height: 8px;
      border-radius: 999px;
      background: #d1d5db;  /* Inactive dot color */
    }

    .dot.active {
      background: #6b7280;  /* Active dot color */
      transform: scale(1.15);  /* Slightly larger when active */
    }
  </style>
</head>

<body>
  <div class="wrap">
    <div class="stage">

      <!-- STEP 1: Welcome card (starts visible with "active" class) -->
      <div id="card-0" class="card active">
        <h1>Welcome</h1>
        <div
          class="image"
          style="background-image: url('https://images.pexels.com/photos/6153129/pexels-photo-6153129.jpeg');">
        </div>
        <p>Build a calm daily habit in minutes.</p>
        <button
          id="next-0"
          class="btn"
          data-onesignal-unique-label="onboarding_next_0">
          Next
        </button>
      </div>

      <!-- STEP 2: Breathe card (starts hidden, shown when user taps "Next") -->
      <div id="card-1" class="card">
        <h1>Breathe</h1>
        <div
          class="image"
          style="background-image: url('https://images.pexels.com/photos/417173/pexels-photo-417173.jpeg');">
        </div>
        <p>Guided breathing whenever you need a reset.</p>
        <button
          id="done"
          class="btn"
          data-onesignal-unique-label="onboarding_done">
          Get Started
        </button>
      </div>

    </div>

    <!-- Progress indicator: 2 dots, first one starts active -->
    <div class="dots" id="dots">
      <div class="dot active"></div>
      <div class="dot"></div>
    </div>
  </div>

  <script>
    (function () {
      /**
       * Switch between cards by toggling "active" class
       * @param {number} i - Index of card to show (0 or 1)
       */
      function setActive(i) {
        // Update card visibility
        document.getElementById("card-0").className = i === 0 ? "card active" : "card";
        document.getElementById("card-1").className = i === 1 ? "card active" : "card";

        // Update progress dots
        var dots = document.getElementById("dots").children;
        dots[0].classList.toggle("active", i === 0);
        dots[1].classList.toggle("active", i === 1);
      }

      // Button: Next (card 0 → card 1)
      document.getElementById("next-0").addEventListener("click", function () {
        setActive(1);
      });

      // Button: Get Started (dismisses the In-App Message)
      document.getElementById("done").addEventListener("click", function (e) {
        // Check if OneSignal IAM API is available
        if (window.OneSignalIamApi && OneSignalIamApi.close) {
          OneSignalIamApi.close(e);  // Dismiss the message
        }
      });
    })();
  </script>
</body>
</html>

Step 3: Customize your content

Safe to customize

You can modify these elements without breaking functionality: Content:

Headline text in <h1> tags
Body copy in <p> tags
Button labels (Next, Get Started)
Image URLs in the background-image: url('...') styles

Visual styling:

Colors: Change .btn background, text color, or dot colors
Spacing: Adjust padding and margins
Typography: Modify font-family, font-size, font-weight
Border radius: Update border-radius values for buttons and images

Adding more steps

To add a third step, follow this pattern:

Add the HTML card:

<div id="card-2" class="card">
  <h1>Your Title</h1>
  <div class="image" style="background-image: url('your-image-url');"></div>
  <p>Your description</p>
  <button id="next-2" class="btn">Next</button>
</div>

Add a progress dot:

<div class="dots" id="dots">
  <div class="dot active"></div>
  <div class="dot"></div>
  <div class="dot"></div> <!-- New dot -->
</div>

Update the setActive() function:

function setActive(i) {
  document.getElementById("card-0").className = i === 0 ? "card active" : "card";
  document.getElementById("card-1").className = i === 1 ? "card active" : "card";
  document.getElementById("card-2").className = i === 2 ? "card active" : "card"; // New card
  
  var dots = document.getElementById("dots").children;
  dots[0].classList.toggle("active", i === 0);
  dots[1].classList.toggle("active", i === 1);
  dots[2].classList.toggle("active", i === 2); // New dot
}

Update the previous step’s button ID: Change id="done" to id="next-1" on card 1’s button, then add a click listener:

document.getElementById("next-1").addEventListener("click", function () {
  setActive(2);
});

Add the dismiss button to the new last card (card-2):

document.getElementById("done").addEventListener("click", function (e) {
  if (window.OneSignalIamApi && OneSignalIamApi.close) {
    OneSignalIamApi.close(e);
  }
});

Keep onboarding flows short (2-4 steps maximum). Users drop off quickly in longer flows. Test completion rates with click tracking.

Step 4: Test the In-App Message

Testing checklist

Save the message in the OneSignal dashboard
Configure delivery settings:
- Set trigger conditions (e.g., session start, specific page view)
- Choose your target audience or select a test user
Send to a test device:
- Use Test Users to preview without affecting production users
- Install your app on a physical device (recommended over simulators for accurate behavior)
Verify functionality:
- ✓ First card appears with correct content
- ✓ “Next” button advances to card 2
- ✓ Progress dots update correctly
- ✓ Fade transitions are smooth
- ✓ “Get Started” button dismisses the message
- ✓ Message doesn’t reappear immediately (check frequency capping settings)

Simulators/emulators may not accurately reflect real device behavior, especially for touch interactions and SDK integrations. Always test on physical devices before launching to production.

Troubleshooting common issues

Issue	Likely cause	Solution
Message doesn’t appear	Trigger conditions not met	Check In-App Message Triggers and verify your test user meets the criteria
Buttons don’t work	JavaScript errors or ID mismatch	Check browser console for errors; verify button IDs match event listener IDs
Images don’t load	CORS issues or invalid URLs	Use HTTPS URLs; test image URLs in a browser first
Message appears but won’t dismiss	OneSignal SDK not loaded	Verify Mobile SDK setup is complete

Next steps

Track user engagement:

Add click tracking using data-onesignal-unique-label attributes (already included in the template) to measure drop-off between steps
View click analytics in Messages → In-App Messages → [Your Message] → Analytics

Personalize the experience:

Tag users who complete onboarding (e.g., onboarding_completed: true)
Use tags to segment users and prevent re-showing the onboarding flow
Add user data to personalize content in future messages

Advanced customization:

Deep link users to a specific screen after dismissal
Use Liquid syntax to personalize headlines with user names or attributes
Implement A/B testing with different onboarding flows to optimize completion rates

Tutorials

Industry strategies

Onboard new users

Engage and convert

Retain and re-engage

Operational

Build a button-driven onboarding carousel

Overview

Prerequisites

How the multi-step flow works

Step 1: Create a new HTML In-App Message

Step 2: Add the HTML template

Step 3: Customize your content

Safe to customize

Adding more steps

Step 4: Test the In-App Message

Testing checklist

Troubleshooting common issues

Next steps

​Overview

​Prerequisites

​How the multi-step flow works

​Step 1: Create a new HTML In-App Message

​Step 2: Add the HTML template

​Step 3: Customize your content

​Safe to customize

​Adding more steps

​Step 4: Test the In-App Message

​Testing checklist

​Troubleshooting common issues

​Next steps

Overview

Prerequisites

How the multi-step flow works

Step 1: Create a new HTML In-App Message

Step 2: Add the HTML template

Step 3: Customize your content

Safe to customize

Adding more steps

Step 4: Test the In-App Message

Testing checklist

Troubleshooting common issues

Next steps