Fix web PaymentElement scrolling in constrained layouts

[khoadng]

Fixes PaymentElement on web when it is placed inside a constrained layout. Fix #2045

Add an optional maxHeight. If Stripe reports content taller than that, the host div is capped and scrolls instead of growing past its parent.

Also adds the missing web stub for setConfirmHandler to make the package compile.

I tested the changes on our project, it is running on the old Flutter version (3.32.8), haven't verify on stable Flutter yet.

---

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Do all checks pass?
• Have you developed the feature on the latest stable version of Flutter?

---

• AI was used to generate or assist with generating this PR. Please specify below how you used AI to help you, and what steps you have taken to manually verify the changes.

AI was used to help inspect the existing web implementation and draft the change. I manually reviewed the changes, tested the patched package in a Flutter web app using a constrained payment sheet, and ran package-level analysis/tests locally.

---

Summary by CodeRabbit

• New Features

  • Payment elements now support maximum height constraints via a new maxHeight parameter for improved layout flexibility.

• Improvements

  • Refined height measurement system for web payment elements with better handling of content sizing and constraint application.
  • Enhanced CSS height management to prevent resizing flicker and improve stability.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds two improvements to the Stripe Flutter web platform. WebStripe now explicitly blocks the setConfirmHandler method with an WebUnsupportedError. PaymentElement gains a maxHeight parameter that caps content height while tracking Stripe's natural measured height separately, preventing repeated resize oscillation and enabling proper scrolling behavior.

Changes

Web Platform Improvements

Layer / File(s)	Summary
WebStripe confirm handler override packages/stripe_web/lib/src/web_stripe.dart	setConfirmHandler override throws WebUnsupportedError, blocking this hook on web.
PaymentElement height capping and measurement system packages/stripe_web/lib/src/widgets/payment_element.dart	New maxHeight parameter (validated > 0) replaces single height state with _measuredContentHeight (Stripe's natural height) and _effectiveHeight (capped applied height). ResizeObserver updates measured height only when uncapped or height exceeds cap, avoiding oscillation. _applyHostHeight centralizes CSS height, minHeight, and conditional maxHeight/overflow. didUpdateWidget recomputes sizing when height or maxHeight change.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• jonasbark
• remonh87

Poem

🐰 The card once jumped and danced about,
But now with maxHeight caps, all doubt is out!
ResizeObserver watches with care,
No oscillation in the air—
Stripe scrolls smooth on the web, hip-hip-hooray! 🌐

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Fix web PaymentElement scrolling in constrained layouts' directly reflects the main changes: adding maxHeight support and improving PaymentElement behavior in constrained layouts to enable scrolling.
Linked Issues check	✅ Passed	The PR directly addresses issue #2045 by implementing maxHeight parameter to enable PaymentElement scrolling in constrained layouts and adding the missing setConfirmHandler stub for web platform compilation.
Out of Scope Changes check	✅ Passed	All changes are within scope: maxHeight parameter and internal height management address the scrolling issue, ResizeObserver updates support proper height tracking, and setConfirmHandler stub ensures platform completeness.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

packages/stripe_web/lib/src/widgets/payment_element.dart (2)

119-121: ⚡ Quick win

Remove redundant style assignments.

Lines 119-120 manually set height and minHeight, but line 121 immediately calls _applyHostHeight() which sets these same properties (along with maxHeight and overflow). The manual assignments are redundant.

♻️ Simplify by removing redundant assignments

     _divElement = web.HTMLDivElement()
       ..id = 'payment-element'
       ..style.border = 'none'
-      ..style.width = '100%'
-      ..style.height = '${_effectiveHeight}px'
-      ..style.minHeight = '${_effectiveHeight}px';
+      ..style.width = '100%';
     _applyHostHeight();

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/stripe_web/lib/src/widgets/payment_element.dart` around lines 119 -
121, Remove the redundant manual style assignments of height and minHeight that
use _effectiveHeight and rely on the existing _applyHostHeight() call to set
height, minHeight, maxHeight and overflow; specifically, in the PaymentElement
widget remove the two lines that set ..style.height = '${_effectiveHeight}px'
and ..style.minHeight = '${_effectiveHeight}px' so that only _applyHostHeight()
configures these properties (keep _effectiveHeight and _applyHostHeight()
as-is).

---

185-195: ⚡ Quick win

Consider allowing horizontal overflow when capped.

When the element is height-capped, line 193 sets overflowX = 'hidden', which prevents horizontal scrolling. If the PaymentElement contains wide form fields, labels, or validation messages that exceed the container width, they would be clipped without any way to view them.

Consider using overflowX = 'auto' to enable horizontal scrolling when needed, or omit setting it entirely to inherit the default behavior.

📜 Proposed change

     _divElement.style
       ..height = heightCss
       ..minHeight = heightCss
       ..maxHeight = _isHeightCapped ? heightCss : ''
-      ..overflowX = _isHeightCapped ? 'hidden' : ''
+      ..overflowX = ''
       ..overflowY = _isHeightCapped ? 'auto' : '';

Or if you want to enable horizontal scrolling when needed:

     _divElement.style
       ..height = heightCss
       ..minHeight = heightCss
       ..maxHeight = _isHeightCapped ? heightCss : ''
-      ..overflowX = _isHeightCapped ? 'hidden' : ''
+      ..overflowX = _isHeightCapped ? 'auto' : ''
       ..overflowY = _isHeightCapped ? 'auto' : '';

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/stripe_web/lib/src/widgets/payment_element.dart` around lines 185 -
195, In _applyHostHeight(), when _isHeightCapped is true the code sets
_divElement.style.overflowX = 'hidden' which can clip wide content; change that
assignment to 'auto' (or remove the overflowX assignment entirely) so horizontal
scrolling is allowed when needed; update the branch that references
_isHeightCapped in _applyHostHeight to use overflowX = 'auto' instead of
'hidden' to ensure wide form fields/labels remain accessible.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/stripe_web/lib/src/widgets/payment_element.dart`:
- Around line 119-121: Remove the redundant manual style assignments of height
and minHeight that use _effectiveHeight and rely on the existing
_applyHostHeight() call to set height, minHeight, maxHeight and overflow;
specifically, in the PaymentElement widget remove the two lines that set
..style.height = '${_effectiveHeight}px' and ..style.minHeight =
'${_effectiveHeight}px' so that only _applyHostHeight() configures these
properties (keep _effectiveHeight and _applyHostHeight() as-is).
- Around line 185-195: In _applyHostHeight(), when _isHeightCapped is true the
code sets _divElement.style.overflowX = 'hidden' which can clip wide content;
change that assignment to 'auto' (or remove the overflowX assignment entirely)
so horizontal scrolling is allowed when needed; update the branch that
references _isHeightCapped in _applyHostHeight to use overflowX = 'auto' instead
of 'hidden' to ensure wide form fields/labels remain accessible.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a4418c17-56cb-4370-bc44-01651db9d839

📥 Commits

Reviewing files that changed from the base of the PR and between 8b8d0eb and a510606.

📒 Files selected for processing (2)

• packages/stripe_web/lib/src/web_stripe.dart
• packages/stripe_web/lib/src/widgets/payment_element.dart