Add `alignment` to `SizeTransition` by IvoneDjaja · Pull Request #177895 · flutter/flutter

IvoneDjaja · 2025-11-02T11:33:55Z

Remove axisAlignment and add alignment to fix #19850

If you had to change anything in the flutter/tests repo, include a link to the migration guide as per the breaking change policy.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

google-cla · 2025-11-02T11:34:00Z

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

gemini-code-assist

Code Review

This pull request refactors SizeTransition to replace the axisAlignment property with a more flexible alignment property. This is a breaking change that gives developers more control over the child's alignment. The changes across the codebase have been updated to use the new alignment property. My feedback focuses on improving the documentation for the new alignment property to accurately reflect its behavior and ensuring that text-direction awareness is preserved in widgets that were updated to use the new API by using AlignmentDirectional where appropriate.

gemini-code-assist · 2025-11-02T11:35:38Z

packages/flutter/lib/src/widgets/transitions.dart

 /// height, depending upon the value of [axis]. The alignment of the child along
-/// the [axis] is specified by the [axisAlignment].
+/// the [axis] is specified by the [alignment].


The documentation here is a bit misleading. It says "The alignment of the child along the [axis] is specified by the [alignment]". However, alignment controls the alignment on both axes, not just the main one defined by axis. It would be clearer to say something like "The alignment of the child is specified by the [alignment]".

/// height, depending upon the value of [axis]. The alignment of the child /// is specified by the [alignment].

Add documentation

packages/flutter/lib/src/widgets/transitions.dart

gemini-code-assist · 2025-11-02T11:35:38Z

examples/api/lib/widgets/raw_menu_anchor/raw_menu_anchor.3.dart

                      shadowColor: colorScheme.shadow,
                      child: SizeTransition(
-                        axisAlignment: position.dx < 0 ? 1 : -1,
+                        alignment: Alignment(-1, position.dx < 0 ? 1 : -1),


The previous implementation used axisAlignment, which SizeTransition internally converted to an AlignmentDirectional. This made it sensitive to the text direction (LTR/RTL). By changing to Alignment, this directionality is lost. To preserve the original behavior, you should use AlignmentDirectional here.

Suggested change

alignment: Alignment(-1, position.dx < 0 ? 1 : -1),

alignment: AlignmentDirectional(-1.0, position.dx < 0 ? 1.0 : -1.0),

Use AlignmentDirectional and fix documentation

gemini-code-assist · 2025-11-02T11:35:38Z

packages/flutter/lib/src/material/refresh_indicator.dart

            right: 0.0,
            child: SizeTransition(
-              axisAlignment: _isIndicatorAtTop! ? 1.0 : -1.0,
+              alignment: Alignment(-1, _isIndicatorAtTop! ? 1.0 : -1.0),


The previous implementation used axisAlignment, which SizeTransition internally converted to an AlignmentDirectional. This made it sensitive to the text direction (LTR/RTL). By changing to Alignment, this directionality is lost. Since RefreshIndicator should respect text direction, it's better to use AlignmentDirectional to preserve the original behavior.

alignment: AlignmentDirectional(-1.0, _isIndicatorAtTop! ? 1.0 : -1.0),

Use AlignmentDirectional and fix documentation

ValentinVignal · 2025-11-03T03:30:11Z

packages/flutter/lib/src/widgets/transitions.dart

+  /// The alignment of the child along the main axis during the transition.
+  final AlignmentGeometry alignment;


This is a breaking change, I'm not sure how we'd want to handle that? Maybe @justinmc has suggestions ?

Add alignment and deprecate axisAlignment

victorsanni

Hi @IvoneDjaja, thanks for the noble effort. However, this is a severely breaking change for any current users of SizeTransition.axisAlignment.

Normally, in these situations, I recommend using dart fix to automatically migrate users. However, here the transformation will be complex because this is a migration from a double to an Alignment. It is theoretically possible to use SizeTransition.axis to figure out how to create an Alignment object (e.g if axis is Axis.vertical and axisAlignment is 1.0, then use Alignment(0.0, 1.0)). But I can't say how doable that is with dart fix.

Overall, while this will lead to a better API, I don't think this is reason enough to break users. IMO the linked issue should be appended to breaking changes that would improve the overall API.

IvoneDjaja · 2025-11-04T02:05:31Z

Hi @victorsanni @ValentinVignal , thank you for your review.

Would it be possible to keep axisAlignment as deprecated while adding the new alignment parameter? This would provide a smooth migration path for existing users while offering a better API for new ones.

Here's what I'm suggesting:

Keep both parameters nullable with an assertion to ensure exactly one is provided:

class SizeTransition extends AnimatedWidget {
  @Deprecated('Use alignment instead.')
  final double? axisAlignment;
  final AlignmentGeometry? alignment;
  ...

  const SizeTransition({
    ...
  }) : assert(axisAlignment == null || alignment == null),

Update the build method to prioritize alignment when available:

Widget build(BuildContext context) {
    return ClipRect(
      child: Align(
        alignment: alignment ?? switch (axis) {
          Axis.horizontal => AlignmentDirectional(axisAlignment, -1.0),
          Axis.vertical => AlignmentDirectional(-1.0, axisAlignment),
        },
        ...

What are your thoughts on this approach?

victorsanni · 2025-11-04T18:26:41Z

Would it be possible to keep axisAlignment as deprecated while adding the new alignment parameter? This would provide a smooth migration path for existing users while offering a better API for new ones.

I'm not sure deprecating a property without a dart fix is a 'smooth' migration. Users will have to manually update their code to adopt the new API, which will require them to re-familiarize themselves with Alignment and SizeTransition APIs, introducing cognitive load. And this cognitive load seems unnecessary given this API doesn't add any new features or behaviors.

There are other places in the framework with similar concerns, we usually document them in breaking changes that would improve the overall API.

Piinks

Hey @IvoneDjaja thanks for contributing! As this is currently proposed, this would be a pretty big breaking change. Usually we introduce the new property, deprecate the old one, and maintain backwards compatibility while the old property is deprecated with a dart fix to help folks migrate. Would you be able to update this PR to do that?

IvoneDjaja · 2025-11-06T11:23:57Z

Hi @Piinks , happy to update the PR 👍 . What do you think of this approach?

Here’s what I think is still needed:

Fix the failing test Linux customer_testing
Fix the failing test Mac customer_testing
Add deprecation with dart fix

Is there an example of how to implement 3. Add deprecation with dart fix?
Please let me know if I’m missing anything.

Piinks · 2025-11-06T18:14:39Z

If this is made backwards compatible, the customer testing likely won't need to be fixed.
Here is one PR where something was deprecated as an example: #161295
Docs on dart fix: https://github.com/flutter/flutter/blob/master/docs/contributing/Data-driven-Fixes.md

dkwingsmt · 2025-11-19T19:19:59Z

Just to confirm, I think we've aligned on how to move forward, right?

IvoneDjaja · 2025-11-20T06:25:43Z

Hi @Piinks and @dkwingsmt, I’ve updated the PR. Please let me know your thoughts.

IvoneDjaja · 2025-11-20T10:13:19Z

packages/flutter/lib/src/widgets/transitions.dart

    this.axis = Axis.vertical,
    required Animation<double> sizeFactor,
-    this.axisAlignment = 0.0,
+    @Deprecated('Use alignment instead. ') this.axisAlignment,


Hi @Piinks, I noticed the deprecation message This feature was deprecated after v3.28.0-3.0.pre. in the referenced PR. Should we include a similar message in this PR as well? If so, what version should we use? I’ll also update the other deprecated annotations accordingly.

@Deprecated( 'Use minimumSize instead. ' 'This feature was deprecated after v3.28.0-3.0.pre.', )

Suggested change

@Deprecated('Use alignment instead. ') this.axisAlignment,

@Deprecated('Use alignment instead. '

'This feature was deprecated after v3.28.0-3.0.pre.',

) this.axisAlignment,

Deprecation format is actually enforced, which is why the analyzer is failing. :)
If you rebase and run flutter doctor, that is the version you would use. Docs: https://github.com/flutter/flutter/blob/master/docs/contributing/Tree-hygiene.md#deprecations

Hi @Piinks, I accidentally rebased on an outdated main, so I had to rebase again and force‐push twice. Could you check this version and let me know if everything looks correct now? :)

Fix deprecation message

ValentinVignal

LGTM! Thank you for the contribution @IvoneDjaja 🎉

victorsanni

Thanks for the PR. Dart fixing with AlignmentDirectional here is a great idea, and allays my fears of a non-smooth transition for users.

This reverts commit 786ed11.

auto-submit · 2026-01-26T12:00:09Z

autosubmit label was removed for flutter/flutter/177895, because - The status or check suite Windows tool_integration_tests_2_9 has failed. Please fix the issues identified (or deflake) before re-applying this label.

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos labels Nov 2, 2025

gemini-code-assist bot reviewed Nov 2, 2025

View reviewed changes

ValentinVignal reviewed Nov 3, 2025

View reviewed changes

victorsanni reviewed Nov 3, 2025

View reviewed changes

IvoneDjaja requested a review from victorsanni November 4, 2025 02:27

dkwingsmt requested review from Piinks and dkwingsmt November 5, 2025 19:21

Piinks reviewed Nov 5, 2025

View reviewed changes

IvoneDjaja requested a review from Piinks November 6, 2025 11:31

github-actions bot added the c: tech-debt Technical debt, code quality, testing, etc. label Nov 20, 2025

IvoneDjaja commented Nov 20, 2025

View reviewed changes

IvoneDjaja force-pushed the size-transition/alignment branch from d2aa4df to 38d821c Compare November 22, 2025 01:04

IvoneDjaja requested review from a team, chinmaygarde, jtmcdole and loic-sharma as code owners November 22, 2025 01:04

github-actions bot added a: tests "flutter test", flutter_test, or one of our tests a: text input Entering text in a text field or keyboard related problems platform-android Android applications specifically labels Nov 22, 2025

ValentinVignal approved these changes Jan 22, 2026

View reviewed changes

victorsanni approved these changes Jan 22, 2026

View reviewed changes

IvoneDjaja added 21 commits January 26, 2026 19:03

Add alignment and remove axisAlignment

1597795

Fix breaking change

7102329

Fix test

af78c39

Use AlignmentDirectional and fix documentation

83f6762

Revert "Add alignment and remove axisAlignment"

88013b0

This reverts commit 786ed11.

Add alignment and deprecate axisAlignment

b57c42b

Add test

4596a85

Add dart fix

e16e2bd

Add dart fix test

57a487c

Fix deprecation message

c603672

Fix deprecation message

167622a

Fix missing dot in deprecation message version

0a934b4

Fix trailing number in deprecation message version

a8c2768

Fix format

bb6420e

Fix format ad info log

fa62c6b

Add documentation

e7cb38d

Add test

bc1de93

Format test

5d4a729

Format test

45eaa51

Fix doc

936e293

Fix doc

2e87eb3

Piinks mentioned this pull request Feb 6, 2026

Flutter Notable Commits - 2026 #181433

Open

	alignment: Alignment(-1, position.dx < 0 ? 1 : -1),
	alignment: AlignmentDirectional(-1.0, position.dx < 0 ? 1.0 : -1.0),

		/// The alignment of the child along the main axis during the transition.
		final AlignmentGeometry alignment;

Conversation

IvoneDjaja commented Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

google-cla bot commented Nov 2, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gemini-code-assist bot Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

victorsanni left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IvoneDjaja commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

victorsanni commented Nov 4, 2025

Uh oh!

Piinks left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

IvoneDjaja commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Piinks commented Nov 6, 2025

Uh oh!

dkwingsmt commented Nov 19, 2025

Uh oh!

IvoneDjaja commented Nov 20, 2025

Uh oh!

IvoneDjaja Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ValentinVignal left a comment

Choose a reason for hiding this comment

Uh oh!

victorsanni left a comment

Choose a reason for hiding this comment

Uh oh!

auto-submit bot commented Jan 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

IvoneDjaja commented Nov 2, 2025 •

edited

Loading

victorsanni left a comment •

edited

Loading

IvoneDjaja commented Nov 4, 2025 •

edited

Loading

Piinks left a comment •

edited

Loading

IvoneDjaja commented Nov 6, 2025 •

edited

Loading

IvoneDjaja Nov 20, 2025 •

edited

Loading