React-Bootstrap v2 and Bootstrap CSS major-version pairing: what is actually supported?

The short answer

React-Bootstrap v2 targets Bootstrap 5, full stop. The authoritative declaration is the peerDependencies entry in the published package, which requires bootstrap@^5.0.0; the documentation restates the same contract. Mixing v2 with Bootstrap 4 CSS is not a supported configuration, and Modal, Tooltip, and Dropdown are the components where a mismatch surfaces first. A hard cutover of the stylesheet — not a gradual CSS migration — is the realistic path.

Where the contract lives

Two places, and they should agree:

1. peerDependencies — the machine-enforced source of truth. Verify it against the exact version you have installed:

npm view react-bootstrap@2 peerDependencies\n# or, for the installed copy:\nnode -p \"require('react-bootstrap/package.json').peerDependencies\"

The ^5.0.0 range means any Bootstrap 5 minor release satisfies the constraint. Compatibility is tracked per major version; there is no per-minor requirement matrix. That said, Bootstrap minor releases occasionally adjust spacing or class details, so pin an exact Bootstrap version in your own package.json rather than floating on the caret range — the library does not formally test every minor combination.

1. The documentation — the human-readable statement that v2 is the Bootstrap 5 line (v1 was Bootstrap 4). For future Bootstrap majors, the project's established pattern is that support lands in a new major of the same react-bootstrap package, not a parallel package name — so upgrade timing is gated on a React-Bootstrap major release, which you should confirm against the project's release notes when the time comes rather than assuming day-one support.

Why gradual CSS mixing fails

React-Bootstrap renders markup built for Bootstrap 5's class and attribute conventions. Bootstrap 5 renamed its data attributes (data-toggle → data-bs-toggle), dropped jQuery, and reworked utilities (e.g., ml-*/mr-* → ms-*/me-*). Serving Bootstrap 4 CSS under v2 components doesn't produce a clean failure — some elements render roughly correctly, which is worse, because spacing, alignment, and interactive states silently degrade. Treat the stylesheet swap as atomic with the package upgrade: bump react-bootstrap and bootstrap together, replace the CSS import, and audit any hand-written markup or third-party plugins that still emit Bootstrap 4 attributes.

Verification: where mismatches show up first

Modal, Tooltip, and Dropdown are the sensitive trio because they depend on positioned overlays, Bootstrap-5-specific classes (.modal-dialog, .dropdown-menu, .tooltip), and Popper-driven behavior. Build one smoke-test page rendering all three, then check the DOM:

• Modal opens with backdrop, correct centering, and dismisses via data-bs-dismiss.
• Tooltip appears on hover/focus with correct placement and arrow.
• Dropdown opens, positions without clipping, and closes on outside click.

If any of these render unstyled or mispositioned, the stylesheet being served is the first suspect — confirm your bundle actually includes Bootstrap 5 CSS (import 'bootstrap/dist/css/bootstrap.min.css' or an equivalent CDN link), since React-Bootstrap ships no CSS of its own. A leftover Bootstrap 4 utility class anywhere in your own markup is a reliable tell of an incomplete migration.

One caveat

This reflects the well-established v1→v2 contract. Peer dependency ranges and docs can shift between patch releases, so run the npm view check above against the exact versions you intend to pin before committing the migration.