mantine-onboarding-tour 4.0.8 — Popovers That Stay on Screen

A default 400px width cap on the tour popover — applied as a CSS class so it survives your own style overrides — fixes both runaway-width popovers and the "position looks broken" reports they caused,

Jul 12, 2026

Introduction

Two bug reports landed within days of each other. One said the tour popover ignored the position prop and clipped off the left edge of the screen. The other said long content blew the popover past the viewport, with no obvious way to rein it in. They looked like two different problems — until they turned out to be the same missing constraint. Version 4.0.8 adds it, and both reports closed with a single fix.

What’s New

A sensible default width for the tour popover

The popover dropdown now has a default max-width of 400px. Previously it grew with width: max-content and no ceiling, so wide or non-wrapping content — an image, a <Code> block, a fixed-width layout — could push it well past the edge of the screen.

The cap is applied as a CSS class on the dropdown rather than inline styles, which matters more than it sounds: it survives any popoverProps.styles.dropdown override of other properties (padding, background, and so on). You only change the width when you explicitly ask to:

<OnboardingTour
  focusRevealProps={{
    popoverProps: {
      // Narrower than the 400px cap:
      width: 320,
      // Or lift the cap for a wider popover (width alone can't exceed max-width):
      styles: { dropdown: { maxWidth: 560 } },
    },
  }}
  tour={steps}
>
  {/* ... */}
</OnboardingTour>

The “broken position” was really a width problem

The second report — a popover that ignored position and stuck to the left edge — had the same root cause. While a tour is active, the component sets overflow-x: hidden on the document to keep portal-rendered popovers from creating horizontal scroll. An unconstrained, too-wide dropdown positioned to the left of a left-edge target had nowhere to go, and the hidden overflow clipped it. Floating UI’s shift middleware can move a popover, but it can’t shrink one. Cap the width, and positioning behaves again — with no position changes required.

Consistent positioning across Mantine versions

Mantine 9.3 flipped the Popover default for preventPositionChangeWhenVisible to true, which pins a popover to the side it opened on and stops it from flipping or shifting while it stays visible. The tour scrolls targets around between steps and relies on continuous re-positioning, so 4.0.8 sets preventPositionChangeWhenVisible: false in its default popoverProps. The behavior is now identical whether you’re on Mantine 9.2 or 9.3+, and you can still opt into the pinned behavior per tour or per step:

<OnboardingTour
  focusRevealProps={{ popoverProps: { preventPositionChangeWhenVisible: true } }}
  tour={steps}
>
  {/* ... */}
</OnboardingTour>

Improvements

Step-level popover config no longer overrides tour-level settings

Tour-level and step-level focusRevealProps are now deep-merged for popoverProps and overlayProps. Before, a step that set its own popoverProps replaced the tour-level object wholesale — so a tour-wide position or style silently vanished for that step. Now a step only overrides the keys it actually sets:

<OnboardingTour
  focusRevealProps={{ popoverProps: { position: 'bottom', shadow: 'xl' } }}
  tour={[
    {
      id: 'step-2',
      title: 'Just this step',
      // Only `position` changes here — the tour-level `shadow: 'xl'` is kept.
      focusRevealProps: { popoverProps: { position: 'right' } },
    },
  ]}
>
  {/* ... */}
</OnboardingTour>

Getting Started

This is a drop-in patch — no API changes, nothing to migrate.

yarn add @gfazioli/mantine-onboarding-tour@4

Compatible with Mantine 9.x and React 18/19 (the peer range stays >=9.0.0). If you were hard-capping the popover width yourself as a workaround, you can drop it — or keep it: an explicit styles.dropdown.maxWidth or width still wins over the new default.

New docs: the Popover width section (with a runnable demo) and the preventPositionChangeWhenVisible note in Scroll Behavior.

Discussion about this post

Ready for more?