{"schemaVersion":"1.0","type":"Article","slug":"mantine-onboarding-tour-v3-responsive-by-design-smoother-than-ever-m48i7","url":"https://api.zyvop.com/mantine-onboarding-tour-v3-responsive-by-design-smoother-than-ever-m48i7","title":"Mantine Onboarding Tour v3 - Responsive by Design, Smoother Than Ever","subtitle":null,"tldr":"Responsive popover positioning, granular lifecycle callbacks, persistent overlay, and type-safe step...","keywords":["react","reactjsdevelopment","TypeScript"],"entities":["Giovambattista Fazioli","Senior Full-stack Engineer, Lead Developer","react","reactjsdevelopment","TypeScript","ZyVOP"],"keyTakeaways":["Responsive popover positioning, granular lifecycle callbacks, persistent overlay, and type-safe step definitions — all in one major release.","Introduction Version 3.0.0 of @gfazioli/mantine-onboarding-tour is a major overhaul that makes guided tours feel polished on every screen size.","The responsive system has been completely redesigned around Mantine's useMatches() pattern, transitions between steps are now seamless, and the API is cleaner and fully type-safe."],"headings":["Introduction","What's New","Responsive Popover Positioning","Granular Tour Lifecycle Callbacks","Persistent Overlay","Type-Safe Custom Step Properties","Smoother Step Transitions","Additional Improvements","Breaking Changes","Migration Guide","1. Replace onOnboardingTourClose","2. Replace responsive props","3. Remove useOnboardingTour import","4. Add generics for custom step properties","Bug Fixes","Links"],"outboundLinks":["https://gfazioli.github.io/mantine-onboarding-tour/","https://www.npmjs.com/package/@gfazioli/mantine-onboarding-tour","https://github.com/gfazioli/mantine-onboarding-tour","https://mantine-extensions.vercel.app/"],"contentText":"Responsive popover positioning, granular lifecycle callbacks, persistent overlay, and type-safe step definitions — all in one major release. Introduction Version 3.0.0 of @gfazioli/mantine-onboarding-tour is a major overhaul that makes guided tours feel polished on every screen size. The responsive system has been completely redesigned around Mantine's useMatches() pattern, transitions between steps are now seamless, and the API is cleaner and fully type-safe. If you're building onboarding experiences with Mantine 8, this release is a significant step forward. What's New Responsive Popover Positioning The old responsive / mobileBreakpoint / mobilePosition toggle has been replaced by something far more powerful: responsive objects on popover props. The position, offset, width, and arrowSize properties now accept breakpoint-to-value maps — the same pattern Mantine uses throughout its ecosystem. <OnboardingTourfocusRevealProps={{ popoverProps: { position: { base: 'bottom', sm: 'right' }, offset: { base: 8, sm: -4 }, width: { base: 'target', md: 350 }, },}}/> Enter fullscreen mode Exit fullscreen mode Each step can also define its own responsive overrides: const steps: OnboardingTourStep[] = [{ id: 'sidebar', title: 'Sidebar Navigation', content: 'Explore the menu items here.', focusRevealProps: { popoverProps: { position: { base: 'bottom', sm: 'right', lg: 'left' }, }, },},]; Enter fullscreen mode Exit fullscreen mode On top of that, Floating UI shift and flip middlewares are now enabled by default — popovers stay within the viewport automatically, no extra configuration needed. Granular Tour Lifecycle Callbacks The single onOnboardingTourClose callback has been replaced with three distinct callbacks that let you react differently to how the tour ends: <OnboardingTouronOnboardingTourComplete={() => { // User finished all steps — mark as completed markTourAsCompleted();}}onOnboardingTourSkip={() => { // User clicked Skip — maybe show later markTourAsSkipped();}}onOnboardingTourEnd={() => { // Always fires — close the UI setStarted(false);}}/> Enter fullscreen mode Exit fullscreen mode The controller also exposes a new skipTour() method for programmatic use in custom popover content. Persistent Overlay The backdrop overlay is now rendered once at the OnboardingTour level and stays visible across step transitions. This eliminates the flicker that occurred when the overlay would unmount and remount between steps. Each step can customize the overlay appearance (color, opacity, blur) via focusRevealProps.overlayProps, with smooth CSS transitions between them. Type-Safe Custom Step Properties No more [key: string]: any. Custom step properties are now declared via a generic type parameter: type MyStep = { icon: string; badge?: string }; const steps: OnboardingTourStep<MyStep>[] = [{ id: 'step1', title: 'Welcome', icon: 'home', badge: 'New' },]; Enter fullscreen mode Exit fullscreen mode The generic flows through OnboardingTourController<T>, so you get full autocomplete and type checking in render functions. Smoother Step Transitions A new two-phase transition mechanism ensures the current popover closes completely before the next one opens. No more flash of the wrong content during navigation. Additional Improvements focusedZIndex prop — Control the z-index of focused elements (default: 201) factory() pattern — OnboardingTour now supports Mantine's factory() API for ref forwarding and Styles API integration Scroll centering — Target elements are always scrolled to center of the viewport; Floating UI handles the rest No more horizontal scroll — overflowX: hidden is applied to <html> while the tour is active Breaking Changes This is a major release with several breaking changes. Here's a quick overview: What changed Action needed onOnboardingTourClose removed Use onOnboardingTourEnd (or the granular callbacks) responsive, mobileBreakpoint, mobilePosition removed Use responsive popoverProps objects useOnboardingTour hook removed from public API Use component props and render functions OnboardingTourStep requires generic for custom props Add <{ myProp: Type }> to OnboardingTourStep popoverProps type is now ResponsivePopoverProps position/offset/width/arrowSize accept responsive objects OnboardingTourOptions type removed from exports Use OnboardingTourBaseProps directly .closeButton and .mobilePopover CSS classes removed Update custom style selectors Migration Guide 1. Replace onOnboardingTourClose The simplest migration — onOnboardingTourEnd is a drop-in replacement: // v2<OnboardingTour onOnboardingTourClose={() => setStarted(false)} /> // v3<OnboardingTour onOnboardingTourEnd={() => setStarted(false)} /> Enter fullscreen mode Exit fullscreen mode 2. Replace responsive props // v2<OnboardingTour responsive mobileBreakpoint=\"sm\" mobilePosition=\"bottom\" /> // v3 — responsive is built-in, no toggle needed<OnboardingTourfocusRevealProps={{ popoverProps: { position: { base: 'bottom', sm: 'left' }, },}}/> Enter fullscreen mode Exit fullscreen mode 3. Remove useOnboardingTour import This hook was internal and created isolated state. Use render functions instead: // v2import { useOnboardingTour } from '@gfazioli/mantine-onboarding-tour'; // v3 — delete the import, use render functions<OnboardingTourcontent={(controller) => <div>Step {controller.currentStepIndex}</div>}/> Enter fullscreen mode Exit fullscreen mode 4. Add generics for custom step properties // v2const steps: OnboardingTourStep[] = [{ id: 's1', price: 9.99 },]; // v3const steps: OnboardingTourStep<{ price: number }>[] = [{ id: 's1', price: 9.99 },]; Enter fullscreen mode Exit fullscreen mode Bug Fixes Popover content flash — No more brief flash of the next step's content inside the current popover during transitions Overlay flickering — Persistent overlay eliminates unmount/remount flicker between steps Horizontal scroll — Portal-rendered popovers no longer cause horizontal scrollbars Popover behind overlay — Popovers now render via portal by default, always appearing above the overlay withinPortal was locked — popoverProps now accepts the full PopoverProps type Links npm: npmjs.com/package/@gfazioli/mantine-onboarding-tour Documentation: gfazioli.github.io/mantine-onboarding-tour GitHub: github.com/gfazioli/mantine-onboarding-tour Mantine Extensions Hub Mantine: Compatible with Mantine 8.x and React 18/19","contentHash":"sha256:457aab82ba713d233dac50fac04d4856aeb7673ac5e5ad653dfa93b937db3cd3","authorName":"Giovambattista Fazioli","authorUrl":"https://api.zyvop.com/author/giovambattista","authorSameAs":["https://gfazioli.github.io","https://github.com/gfazioli","https://x.com/gfazioli","https://www.linkedin.com/in/giovambattistafazioli/"],"category":null,"tags":["react","reactjsdevelopment","TypeScript"],"audience":"Readers researching react","tone":"Professional, senior full-stack engineer, lead developer perspective","readingTimeMinutes":4,"wordCount":828,"faqs":null,"primaryTopic":"react","publishedAt":"2026-09-04T09:21:25.366Z","updatedAt":"2026-09-04T09:21:25.366Z","canonicalUrl":"https://dev.to/undolog/mantine-onboarding-tour-v3-responsive-by-design-smoother-than-ever-4n82"}