When faced with the task of building my own onboarding flow for ProseBird I was pretty lost. Despite being onboarded to countless services throughout my life, I had never looked at it from the developer's perspective.

Rather than going in blind and wasting time on pointless iterations, I needed to first answer a crucial question: what do I want my onboarding to accomplish?

Initially, this seemed straightforward. My app doesn't require complex setup like identity verification or payment processing, I just needed additional information from users beyond the email they used to create their account.

Turns out that onboarding can be much more than simple data collection. A well-designed onboarding experience can attract new users, understand their needs, generate marketing insights, and even create an emotional connection between users and your product.

That's a lot to accomplish, and without a clear strategy it can get pretty overwhelming really fast. So I outlined four core objectives for my onboarding flow:

1. Personalize the user experience: Creating tailored interactions based on user identity, type, and intended use.

2. Generate product insights: Understanding user segments, expectations, and behaviors to guide development decisions.

3. Drive network growth: Leveraging existing users to expand the platform through collaboration.

4. Capture marketing intelligence: Tracking acquisition channels and attribution for strategic optimization.

Design Approach

When researching onboarding patterns, I found two main presentation styles: modal overlays and dedicated pages.

Modal-based onboarding presents the flow as an overlay while showing glimpses of the dashboard behind it. This approach suggests the onboarding is just a brief step before reaching the main experience. Dedicated page onboarding, on the other hand, gives the process full attention and encourages users to invest more time in completing it thoughtfully.

Neither approach is inherently better, the differences aren't massive, and most users probably don't consciously notice the distinction. Initially, I chose the modal approach because it felt simpler. However, after adding the steps, controls, copy, header, and images, the modal felt too cramped. This was a good sign to migrate to a dedicated page, allowing the layout to breathe a little.

A design pattern I knew I wanted to implement was the split view, commonly used in authentication and onboarding flows. Split views divide the screen into two sections, typically content on one side and a form on the other.

I was drawn to this pattern partly because it's so prevalent (and when done well, looks professional), but I'll admit that fear of incorrectly handling whitespace in a single-column layout also played a part in my decision.

Ultimately, studying good and bad onboarding designs was helpful but I couldn't find complete flows to directly replicate. Most inspiration came from individual design patterns like the split view mentioned above.

This was expected since onboarding flows are inherently unique to each application's specific needs and user base. For that reason, I focused on matching my app's style, following established UX principles, and iterating until it felt cohesive and asthetically pleasing (spoiler: it took a lot of iterating).

Progress Indication

One often overlooked element I implemented was clear progression tracking. Users can see exactly which step they're on and how many remain, displayed as both a progress bar and step counter.

This addresses a fundamental psychological principle: people are more likely to complete tasks when they can visualize progress and see the end point. As a user I agree, and as a developer I think it looks nice. Moving on.

The Five Steps

With objectives and design decisions out of the way, I created the actual user journey. Here's each step in order of appearance and the reasoning behind them:

1. Basic Information

Unique user identifiers in ProseBird are email addresses. Users can invite others to edit and present scripts through email, even if invitees don't have accounts yet. Once invited, it would be awkward to refer to your teammates by their email address.

Rather than implementing traditional usernames or handles, I chose display names. This approach maintains email as the primary identifier while allowing more natural, personalized interactions between users during collaborative sessions.

This step also prompts users to upload a profile picture. If they choose not to, a dynamically colored fallback image displays their initials based on their display name. This ensures every user has a visual identity during collaboration, whether they upload a custom image or not.

The step remains simple and straightforward, allowing users to quickly progress while establishing their visual presence in the app.

2. User Type

This step collects valuable segmentation data to guide product development decisions.

I identified two primary user types:

• Students: From high school through college, needing concise and engaging presentation tools.

• Professionals: Including marketing experts, salespeople, professors, and business leaders who require reliable, high-quality presentation solutions.

Understanding the ratio between these segments is perhaps the most fundamental data point for prioritizing product improvements and feature development.

In addition to these two, a third user type called "Personal" was added to account for users who didn't fit the mold of the first two. Examples of Personal users include: hobbyists, content creators, community organizers, and more.

3. Intent

This step focuses on understanding what users expect ProseBird to help them accomplish.

By allowing users to select specific activities they'll use ProseBird for, they're indirectly communicating which features matter most to them. Combined with ongoing user feedback, this data provides powerful insights into how different user segments interact with the product.

An argument can be made that this is the most strategically important step in the onboarding process, as it directly informs product decisions.

4. Team Collaboration

Collaboration is core to ProseBird's value proposition. The ability to seamlessly coordinate multi-speaker presentations in real time is what sets it apart from boring old teleprompters.

With this in mind, users can inform whether they plan to work alone or with a team. For instance, a YouTuber will likely use the app solo, while college students might need to present group projects collaboratively.

The intention behind this step goes beyond gathering user insights. By allowing new users to provide their potential teammates' email addresses, it's effectively driving organic growth. Referenced individuals receive platform invitations, and having their contact information creates opportunities for future engagement regardless of whether they join immediately.

This step also establishes groundwork for a potential referral system, where successful referrers could share revenue from new paid users they bring to the platform.

5. Attribution Tracking

The fifth and final step asks users how they discovered ProseBird.

This step is standard practice in most SaaS products and serves purely marketing attribution purposes. Understanding which channels drive the highest-quality users helps optimize acquisition spending and strategy.

Common Approaches

If you’re using vanilla JavaScript and HTML, your solution might look like this:

<div id="dropdown">Dropdown Content</div>

<script>
  const dropdown = document.getElementById('dropdown');

  document.addEventListener('click', function (event) {
    if (!dropdown.contains(event.target)) {
      // Handle outside click
      dropdown.style.display = 'none';
    }
  });
</script>

In a React environment, you’d likely do something like this:

useEffect(() => {
  function handleClick(e) {
    if (ref.current && !ref.current.contains(e.target)) {
      onOutsideClick();
    }
  }

  document.addEventListener("mousedown", handleClick);
  return () => document.removeEventListener("mousedown", handleClick);
}, []);

Maybe wrap it in a custom hook:

function useOutsideClick(ref, callback) {
  useEffect(() => {
    function handleClick(e) {
      if (ref.current && !ref.current.contains(e.target)) {
        callback();
      }
    }

    document.addEventListener("mousedown", handleClick);
    return () => document.removeEventListener("mousedown", handleClick);
  }, [ref, callback]);
}

Why I Didn’t Use a Library

Now, you might ask: couldn't I just use something like useClickAway from react-use or useOutsideClick from Headless UI? Absolutely!

While my version is slightly optimized for my needs by accepting multiple exception refs, the true as to why I built it from scratch is... because i felt like it.

I usually favor the DIY route, I knew it wouldn’t take much time, and figured it might even be instructive. Luckily, these assumptions ended up being correct, something that doesn’t happen as often as I would like.

Implementation

Usage

Wraps any content and triggers a callback (onOutsideClick) when the user clicks anywhere outside of it, unless the click happens in an exception zone.

<OutsideClickHandler 
    onOutsideClick={() => console.log("Clicked outside!")}
    exceptionRefs={[exceptionRef]}
>
    {/* content */}
</OutsideClickHandler>

Props

children (required): The content you want to protect or track clicks outside of.

onOutsideClick (required): A function that fires when the user clicks outside the main element (and any exceptions).

exceptionRefs (optional, default = []): An array of refs to other elements you want to ignore in the outside click logic (like tooltips, buttons, floating menus).

isActive (optional, default = true): A boolean to enable or disable the behavior dynamically.

useEffect

1. Attaches a mousedown listener to the document on mount.

2. On every click, checks:

   • Whether the click is outside the main ref.

   • And outside all exception refs (.every()).

3. If both conditions are met, calls onOutsideClick().

4. Cleans up the listener on unmount or when isActive changes, avoiding memory leaks or duplicate handlers.

Design Advantages

• Encapsulated: Keeps outside-click logic self-contained and clean.

• Flexible: Supports multiple exception zones (unlike most hooks).

• Declarative: Feels like wrapping behavior around content, rather than injecting logic.

Demo

Source code

The full code is available on GitHub.

ProseBird taught me more in a few months than four years of college ever did. The reason is simple: I didn’t build around what I already knew. I built what the idea demanded, and learned the skills as I went.

Taking on ProseBird meant being okay with stepping out of my comfort zone and starting from scratch in many ways. When I started, I didn’t know Next.js, Tailwind CSS, TypeScript, Stripe, PostHog, the list goes on. But catering to my project's needs instead of my own meant I had to figure them out, one by one, sometimes even multiple at once.

And those were just tools. Let alone how individual features forced me to dive into entire areas I had never touched. Stuff like string distance algorithms (Levenshtein) for the spoken-word alignment system, or voice-to-text AI and speech recognition.

Imposing limits on your product just because they exceed your current skills is one of the worst things a technical founder can do. If you want to grow fast, your skill set has to follow the idea, not the other way around.

2. “Don't run away from hard problems”

It’s natural to want to avoid work that feels like it’ll drain a disproportionate amount of time and energy. For me, nothing amplifies that feeling more than uncertainty.

To me, spending hours coding isn’t the end of the world. Maybe you hit a few bumps along the way but at least you can see the finish line. On the other hand, if I’m using that same time and energy digging through new documentation and searching for the “ideal” implementation, that’s a mind-numbing game with no end in sight, one that often leads nowhere.

Regardless of the type, putting off problems like these won’t make them disappear, you’ll have to face them sooner or later. In my experience, whether I tackle an issue right away or put it off for a week, the result is almost always the same: it takes just as long to solve. The only difference is that I ended up delaying progress by a full week for no reason.

You probably won’t wake up tomorrow with a breakthrough that drastically reduces time and effort. So you might as well start now and be done by then.

On top of that, starting with the biggest concerns in a project is often the smartest path forward. These are the problems that tend to define the viability of entire sections, or even the whole project. Solving them early gives you a much clearer picture of both feasibility and strategy.

3. “Don't paste code you don't understand”

This one might be controversial since most developers are guilty of it at some point. And with the rise of vibe coding, falling into this trap is easier than ever. But what makes committing to code you don’t quite understand such a bad thing?

Let’s say you’re working on a school project due in four days.

Day 1:
You paste a useEffect or setTimeout from StackOverflow or ChatGPT. You don’t really get it, but it works, so you move on.

Day 2:
You add a custom hook, then debounce, then a library. Logic overlaps and you patch bugs without knowing what actually fixed them.

Day 3:
By this point it’s a black box you’re afraid to touch. You comment stuff out, rewatch tutorials, copy even more code but nothing actually solves the root problem.

Day 4:
Deploys break, you stop refactoring, momentum dies. Now you have to pull an all-nighter, rewrite half of your codebase and pray to be done by the time the sun comes up. Yikes.

A full-on snowball effect, all because you didn’t stop to understand the first few lines.

Personally, once I started treating StackOverflow and AI as teachers instead of shortcuts, I never needed them more than once or twice with any given problem before I could solve it confidently on my own.

4. “Hold the bar as high as you can”

When I say “bar,” I mean the metaphorical one, the standard you use to decide whether something is “good enough”.

Mine’s been comfortably high for as long as I can remember. Credit goes to my mom, who drilled that into me early on, and I, for either fear of repercussion or plain peer pressure, held onto it through middle school, high school, and college. Not the best of reasons, but hey, I turned out fine.

Jokes aside, this mindset is one of the most OP life traits you can develop, because it works like a muscle. The more you hold yourself to a high standard, the sharper your critical thinking and prioritization skills get. Whether you're judging someone else's work or doing something yourself, you can tell if it's good, bad, or absolute garbaggio, and you'll often be right.

Living by this naturally takes a toll on your well-being. The tradeoffs are mild neuroticism, hair loss and a potentially shorter life expectancy, but it's not like you can't turn it off from time to time.

In fast-paced environments where speed matters, this principle can easily be mistaken for paralyzing perfectionism. That’s not the point. It’s less about shipping perfect work right away, and more about knowing what a high-bar outcome looks like, then work toward it with every iteration.

5. “When your body talks, you listen”

This last one is simple, but often overlooked, and I couldn’t leave it out.

Before I internalized this as a principle, I lost countless nights trying to brute-force my way through problems to no success, only to revisit the same issue the next morning with a fresh perspective and solve it in a fraction of the time.

The idea is simple: your brain stops working right past a certain threshold of stress or exhaustion. That threshold varies from person to person, but once you hit it, you’re just wasting time pretending otherwise.

In my experience, pushing through those limits is often encouraged, sometimes even romanticized, as part of the hustle that comes with building something on your own. And sure, there’s truth to that. I still try to push myself when it counts.

But the real skill is knowing when to call it a day. Otherwise, it turns into a pointless game with no winners.

The Tooltip Problem

So when I realized I needed tooltips in my app, the first place I looked was HTML’s native title attribute. I had basically zero experience implementing tooltips, but I knew from prior work that for most common UI elements, there are usually three main options:

1. Use a native browser feature (like title)

2. Import a UI library or headless component system (like shadcn/ui)

3. Build your own from scratch

Comparing the Options

To figure out which option made the most sense for my use case, I first needed to understand their pros and cons. Here's the breakdown.

My goal with tooltips in this application was to make them customizable and reusable. I wanted to easily create and plug-in different tooltip types for different use cases, each with its own styling, positioning, and data, while still behaving predictably and reliably.

What I had in mind looked something like this:

<TooltipWrapper
  type="moreInfo"
  options={options}
>
  <a href="#">Hover me</a>
</TooltipWrapper>

This is completely outside the realm of what vanilla HTML is capable of, but perfectly doable with most tooltip libraries out there. The limitations start to show if, for instance, I wanted to fetch user data, treat it, and display it as an image and some text, all from within the tooltip component.

You could argue this is an extreme edge case, or that I could just fetch and prepare all the data in the parent component beforehand. And honestly, those are both valid criticisms.

Still, I'd rather implement a complete solution upfront than go through the trouble of dealing with tooltips again later. You have to choose your battles, and for better or worse, this was the choice I went with.

Initial Implementation

Now for the trickiest part: the wrapper.

My initial implementation of the tooltip wrapper accepted the following parameters:

• children (required): The anchor element or component that the tooltip is attached to.

• position (optional, default = "top"): Where the tooltip should appear relative to the anchor.

• className (optional, default = ""): Tailwind utility classes for styling the wrapper element.

• tooltipType (optional, default = DefaultTooltip): The custom tooltip component used to render the content.

• data (required): The actual data passed to the tooltip, ranging from raw text to functions and everything in between.

The wrapper itself was styled with position: relative so the tooltip could be positioned inside its bounds. It returned the following structure:

<div className="relative group" ref={wrapperRef}>
  {children}
  <TooltipComponent
    ref={tooltipRef}
    data={data}
    className={`fixed z-[9999] opacity-0 group-hover:opacity-100 pointer-events-none ${className} ${getTranslateClass()}`}
    style={{ top: tooltipPosition.top, left: tooltipPosition.left }}
  />
</div>

This layout allowed the tooltip’s position to be calculated like this:

const updateTooltipPosition = () => {
  if (wrapperRef.current && tooltipRef.current) {
    const wrapperRect = wrapperRef.current.getBoundingClientRect();
    const tooltipRect = tooltipRef.current.getBoundingClientRect();

    const positions = {
      top: {
        top: wrapperRect.top - tooltipRect.height,
        left: wrapperRect.left + wrapperRect.width / 2 - tooltipRect.width / 2,
      },
      bottom: {
        top: wrapperRect.bottom,
        left: wrapperRect.left + wrapperRect.width / 2 - tooltipRect.width / 2,
      },
      left: {
        top: wrapperRect.top + wrapperRect.height / 2 - tooltipRect.height / 2,
        left: wrapperRect.left - tooltipRect.width,
      },
      right: {
        top: wrapperRect.top + wrapperRect.height / 2 - tooltipRect.height / 2,
        left: wrapperRect.right,
      },
    };

    setTooltipPosition(positions[position]);
  }
};

useEffect(() => {
    updateTooltipPosition();
    window.addEventListener("resize", updateTooltipPosition);
    return () => {
      window.removeEventListener("resize", updateTooltipPosition);
    };
}, [position]);

The wrapper naturally wrapped around the anchor component, meaning it would never be larger than the anchor itself. This setup ensured the tooltip could be absolutely positioned in relation to its parent without weird overflow or layout issues.

One important limitation: this version didn’t support click-based tooltips. Since everything was triggered on hover, a simple group class on the wrapper combined with group-hover was enough to control visibility.

Instead of hard-setting the tooltip’s position with fixed values per direction, I kept it neutrally placed and used a translation based on the desired direction. That way, it could animate smoothly from its origin point:

const getTranslateClass = () => {
  const translations = {
    top: "group-hover:-translate-y-4",
    bottom: "group-hover:translate-y-4",
    left: "group-hover:-translate-x-4",
    right: "group-hover:translate-x-4",
  };
  return translations[position];
};

The result was a customizable, modular tooltip that popped in and out of view with smooth transitions on hover.

Where It Fell Short

It didn’t take much testing to realize how deceptively complicated tooltips can be. Here are the two main ways they didn’t behave as expected in this version:

Positioning:
The tooltip’s position wasn’t dynamic, it didn’t track layout changes in real time. Once the anchor element moved (due to a resize, animation, or DOM change), the tooltip often stayed stuck in its original spot, floating somewhere random on the screen. That made it completely unreliable. This happened because I was only recalculating its position on window.resize, ignoring internal layout shifts entirely.

tooltip mispositioned after layout change

Visibility / Display:
The tooltip component was always present in the DOM, even when it wasn’t visible. It stayed hidden using CSS (opacity: 0 and pointer-events: none), but never actually unmounted. That meant it was still detectable when inspecting the DOM, and sometimes even interfered with hover and click behaviors. This happened because I never tied its presence to a true visibility state, I was only toggling styles, not whether it should exist at all.

tooltip "shadow" still visible in the DOM

Switching to Floating UI + Framer Motion

Confronted with these issues, my options were twofold: I could either stick with the full DIY implementation and fix its problems individually, or look for a more established solution. Taking performance and long-term reliability into account, I ended up going with the second. If I was going to over-engineer this, I might as well do it the right way.

It didn’t take long to find Floating UI (formerly Popper), a general-purpose abstraction for handling floating positioning. That was perfect because unlike fully pre-built tooltip components, Floating UI wouldn’t confine me to rigid designs or assumptions. I’d get the flexibility I wanted, at the cost of writing a bit more code to set up.

I also decided to offload transitions and animation to Framer Motion, since it gives you more control over the animation flow.

Final Version Breakdown

With the new version in place, here’s a summary of what changed and why:

• No need for ResizeObservers or useEffect hacks to track anchor position, Floating UI now handles dynamic positioning automatically using autoUpdate and element refs.

• Transitions are now handled by Framer Motion, so all Tailwind transition classes were removed.

• The tooltip component is now conditionally mounted with AnimatePresence, fixing the old “invisible but still in the DOM” issue.

• New wrapper parameters:

  • delay: optional animation delay (default is 0.5)

  • disabled: disables tooltip triggers entirely

  • openOn: defines the trigger action (click or hover)

• Tooltips triggered by clicks are now dismissed via an OutsideClickHandler.

Here’s a high-level overview of how the new tooltip system works in practice:

1. Anchor elements are wrapped in TooltipWrapper and passed custom parameters based on need.

    <TooltipWrapper
      tooltipType={CustomTooltip}
      position="bottom"
      openOn="click"
      delay={0.1}
      data={{ text: "Hi!" }}
    >
      <button>Click me</button>
    </TooltipWrapper>
   

2. The wrapper handles trigger detection, positioning, visibility, and state, and displays the desired tooltip component. If none is specified, it falls back to DefaultTooltip.

    {open && (
      <motion.div
        ref={refs.setFloating}
        initial={{ opacity: 0, scale: 0.9, ...pullAway }}
        animate={{ opacity: 1, scale: 1, x: 0, y: 0 }}
        exit={{ opacity: 0, scale: 0.9, ...pullAway }}
        transition={{ duration: 0.2, delay, ease: "easeInOut" }}
        style={{
          position: strategy,
          top: y ?? 0,
          left: x ?? 0,
        }}
        className="z-[9999] pointer-events-none"
      >
        {React.createElement(tooltipType, { data })}
      </motion.div>
    )}
   

3. Tooltip components themselves can be as simple or complex as needed, making them easy to reuse and tailor per use case.

    const DefaultTooltip = forwardRef(({ data, className = "", style }, ref) => (
      <div ref={ref} className={`tooltip-default ${className}`} style={style}>
        {data.text}
      </div>
    ));
   

Although the changes are somewhat drastic under the hood, the result is visually the same. The real difference is in consistency, reliability, and long-term flexibility. This version doesn’t break on layout shifts, doesn’t leave ghost tooltips behind, and provides full control over when, how, and what gets rendered.

Source code

The full code for both tooltip versions is available here.