Add Option to disable full selection on focus on TextField, TextFormField, and EditableText #163491

camfrandsen · 2025-02-17T16:57:33Z

This allows overriding the default behavior of highlighting all the text
on focus when using web or desktop

This is adding a field to EditableText, TextField, and TextFormField to disable highlighting the entire field on web and desktop when it receives focus. The field is called highlightAllOnFocus. It does nothing on other platforms because the other platforms don't highlight the entire field on focus.

Note: I am not attached to this variable name, but it was the best I could think of... But I am very open to better suggestions 😆

Thank you for everything!

Issue: #163399

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.

This allows overriding the default behavior of highlighting all the text on focus when using web or desktop

justinmc

Thanks for jumping in and submitting a PR for this. Some questions here. I always hesitate to add a new parameter to TextField, so I want to make sure we get it right.

When the user dismisses the modal, we want the focus to go back the text field with the same selection that it had before.

What platform is this on? Is this the same behavior that you would expect if you tab into that field?

Some other possible paths here for completeness:

Keep the boolean parameter as-is in this PR, but set it to a default value that considers the current platform.
Somehow give the user more generic control over what happens when the user focuses the field (make the parameter a function instead of a bool?).

justinmc · 2025-02-26T16:42:02Z

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

+  /// web or desktop
+  ///
+  /// By default this will highlight the text field on web and desktop, and can
+  /// only be turned off on those two platforms


Missing a period at the end of the sentence here and above.

justinmc · 2025-02-26T16:46:49Z

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

@@ -1792,6 +1793,15 @@ class EditableText extends StatefulWidget {
  /// {@endtemplate}
  bool get selectionEnabled => enableInteractiveSelection;

+  /// {@template flutter.widgets.editableText.highlightAllOnFocus}
+  /// Whether or not this field should highlight all text when gaining focus on
+  /// web or desktop


The special case for web and desktop makes me hesitate here. I know that's how it works now, though. What happens in a native iOS or Android app if you connect a hardware keyboard and use the tab key to move between fields?

camfrandsen · 2025-02-28T05:35:41Z

@justinmc Yeah! Thank you for taking the time to help me with this! The last thing I want to do is mess up flutter 😆 So I appreciate the questions!!
For us, this is a web only application. Which normally, we would want it to select all the text, but unfortunately in a few cases we don't... And for us, if they were to tab into these certain fields we also wouldn't want it to select everything.
Having said that, I love the idea of making it a function. It give a lot for flexibility in what would happen. I can make that change. Would I just call it onFocusChange similar to a focus node?
Actually, clarification question. Do you think it would be a void Function() that would be called instead of setting selection (if not null) or should it just be a TextSelection Function()?

justinmc

@camfrandsen Sorry for the slow response (vacation). Have you had any luck with the function? I'm thinking of something that would completely replace _adjustedSelectionWhenFocused, but that might not be practical since _adjustedSelectionWhenFocused uses private members currently. But would that kind of approach work for your use case or is it not doable?

Otherwise, what if your existing boolean parameter defaulted to something like this?

  static bool get defaultHighlightAllOnFocus {
    if (kIsWeb) {
      return true;
    }
    return switch (defaultTargetPlatform) {
      TargetPlatform.android => false,
      TargetPlatform.iOS => false,
      TargetPlatform.fuchsia => false,
      TargetPlatform.linux => true,
      TargetPlatform.macOS => true,
      TargetPlatform.windows => true,
    };
  }

Then we could remove the line about highlightAllOnFocus only applying to web and desktop? I'm just trying to make sure that this parameter makes sense and doesn't have any strange behavior that's dependent on our current private approach.

justinmc · 2025-03-13T21:51:21Z

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

+  /// By default this will highlight the text field on web and desktop, and can
+  /// only be turned off on those two platforms
+  /// {@endtemplate}
+  final bool highlightAllOnFocus;


Actually this should probably be called selectAllOnFocus.

setCustomSelectionOnFocus allows developers to set the selection when the text field gets focus

camfrandsen · 2025-03-22T18:13:31Z

@justinmc No worries! I realize that you have probably a ton of stuff going on 😆
So, I personally love the callback idea! It allows for a lot of customization but keeps the API simple. They don't really need access to the private variables since you can access them through the public getters.
I pushed up my attempt at it. Let me know what you think 😄

justinmc

Does this approach work for your use case? I worry about the private variables in the current _adjustedSelectionWhenFocused implementation:

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

Lines 4641 to 4646 in a0b1b32

    
           final bool shouldSelectAll = 
        
               widget.selectionEnabled && 
        
               (kIsWeb || isDesktop) && 
        
               !_isMultiline && 
        
               !_nextFocusChangeIsInternal && 
        
               !_justResumed;

Those won't be available to app developers that write their own setCustomSelectionOnFocus, so they won't be able to recreate the existing behavior exactly.

justinmc · 2025-04-02T19:08:57Z

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

@@ -1798,6 +1802,14 @@ class EditableText extends StatefulWidget {
  /// {@endtemplate}
  bool get selectionEnabled => enableInteractiveSelection;

+  /// {@template flutter.widgets.editableText.setCustomSelectionOnFocus}
+  /// Set a custom text selection when focus is given


Missing a period here.

justinmc · 2025-04-02T19:14:27Z

packages/flutter/test/widgets/editable_text_test.dart

+            style: Typography.material2018().black.titleMedium!,
+            cursorColor: Colors.blue,
+            backgroundCursorColor: Colors.grey,
+            setCustomSelectionOnFocus: () => controller.selection,


Nit: Maybe set this to something different so that it's more obvious that it worked, and not that it just kept the existing selection.

camfrandsen · 2025-04-07T15:52:30Z

@justinmc Great question, it does work for us, but that doesn't mean it would work for everyone. This is how I broke it down in my head:

widget.selectionEnabled - This was passed in, so they should know this value
(kIsWeb || isDesktop) - This is available to everyone already
!_isMultiline - This is just if they set maxLines > 1, so I feel like they would already know this
The next two (!_nextFocusChangeIsInternal and !_justResumed) are tricker... They could replicate the AppLifecycleListener and focus node listeners... but it would be better if it didn't have to be duplicated...

I could pass those two variables into the function so that developers could use them. Would it be better to add them later once there is a use case for them, or add them now so that if they are added later, there isn't a migration change for them?

…selection changed Add missing period to document

justinmc

tl;dr I think we should go back to your boolean approach.

I'm sorry for all of the back and forth here, but I feel more confident in the boolean approach after exploring the function approach first. I think the function approach is probably still the best way to do this, but given how EditableText is currently written, it's not practical to do it that way without bigger refactoring and/or an API that might be a big maintenance burden.

If we were going to do the function approach, I think we would need _adjustedSelectionWhenFocused to be rewritten as a static default value for setCustomSelectionOnFocus. That way developers could fall back to the default behavior, something like this:

TextField(
  setCustomSelectionOnFocus: (...) {
    if (mySpecialCase) {
      return TextSelection(...);
    }
    return EditableText.defaultSetCustomSelectionOnFocus(...);
  },
),

But the API will get pretty tricky if we do that. I say go back to the boolean. Is it possible to do it with a default value like I mentioned in #163491 (review)?

justinmc · 2025-04-11T22:43:12Z

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

@@ -163,6 +163,7 @@ class TextFormField extends FormField<String> {
    Brightness? keyboardAppearance,
    EdgeInsets scrollPadding = const EdgeInsets.all(20.0),
    bool? enableInteractiveSelection,
+    SetCustomSelectionOnFocus? setCustomSelectionOnFocus,


Could you also pipe the parameter through for CupertinoTextField?

Defaults to true on web

camfrandsen · 2025-04-15T21:54:59Z

@justinmc I changed it back to a boolean. Thank you again for your help on this! Sometimes we have to try something to realize some of the pros and cons, so I am not worried at all about switching it to a function and back 😆

justinmc

I appreciate your flexibility! I'm convinced that the boolean+default is the way to do it now looking at this code. Just some smaller improvements here.

justinmc · 2025-04-24T20:45:57Z

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

+  /// Whether or not this field should highlight all text when gaining focus on
+  /// web or desktop.


"highlight" => "select". Just to make sure that we're consistent with our wording.

In another comment in this review I suggested that this parameter should apply equally to all platforms. If so then you should also remove "on web or desktop" here.

justinmc · 2025-04-24T20:49:46Z

packages/flutter/lib/src/cupertino/text_field.dart

@@ -289,6 +289,7 @@ class CupertinoTextField extends StatefulWidget {
    this.scrollPadding = const EdgeInsets.all(20.0),
    this.dragStartBehavior = DragStartBehavior.start,
    bool? enableInteractiveSelection,
+    this.selectAllOnFocus,


Can you also set the same defaultSelectAllOnFocus default value for all of the parameters that you added, even these passthrough ones? In my opinion that's the most unambiguous way to handle passthrough parameters with default values.

@justinmc I totally agree that is the most unambiguous way. I can do that easily for text_form_field (and did in my last commit), but material and cupertino text_field are not so straight forward since their constructors are currently const. If I wanted to default selectAllOnFocus to EditableText.defaultSelectAllOnFocus I would need to remove const from the constructor. Is that still worth it?

Ah good point. I say leave them with no default in the case of const constructors.

justinmc · 2025-04-24T20:51:12Z

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

@@ -4644,6 +4670,7 @@ class EditableTextState extends State<EditableText>
      TargetPlatform.macOS || TargetPlatform.linux || TargetPlatform.windows => true,
    };
    final bool shouldSelectAll =
+        widget.selectAllOnFocus &&
        widget.selectionEnabled &&
        (kIsWeb || isDesktop) &&


I think we can get rid of this line. This logic is encoded in defaultSelectAllOnFocus. Furthermore, if we remove this line, then selectAllOnFocus applies equally to all platforms, which I think is more clear for developers that are trying to understand what this parameter does.

justinmc · 2025-04-24T20:52:59Z

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

+  /// By default this will highlight the text field on web and desktop, and can
+  /// only be turned off on those two platforms.


And again along with my comment that this parameter should apply equally to all platforms, you would have to remove "and can only be turned off on those two platforms."

justinmc · 2025-04-24T20:54:45Z

packages/flutter/test/widgets/editable_text_test.dart

@@ -16212,6 +16212,35 @@ void main() {
      skip: !kIsWeb, // [intended]
    );

+    // Regression test for https://github.com/flutter/flutter/issues/163399.
+    testWidgets('when selectAllOnFocus is turned off', (WidgetTester tester) async {


Can you also test when this is set to true? With my comment about how the parameter should apply equally to all platforms, the behavior of true is different than the default behavior.

Fix comments now that selectAllOnFocus is not platform specific

justinmc

A few comments, otherwise good to go. I'll look for a secondary reviewer.

justinmc · 2025-05-01T20:21:22Z

packages/flutter/lib/src/cupertino/text_field.dart

@@ -289,6 +289,7 @@ class CupertinoTextField extends StatefulWidget {
    this.scrollPadding = const EdgeInsets.all(20.0),
    this.dragStartBehavior = DragStartBehavior.start,
    bool? enableInteractiveSelection,
+    this.selectAllOnFocus,


Ah good point. I say leave them with no default in the case of const constructors.

justinmc · 2025-05-01T20:22:55Z

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

@@ -882,6 +882,7 @@ class EditableText extends StatefulWidget {
    this.keyboardAppearance = Brightness.light,
    this.dragStartBehavior = DragStartBehavior.start,
    bool? enableInteractiveSelection,
+    bool? selectAllOnFocus,


This one could default to defaultSelectAllOnFocus right?

Yeah :) I default it on line 927 since defaultSelectAllOnFocus isn't a const value

justinmc · 2025-05-01T20:28:33Z

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

@@ -1798,6 +1800,13 @@ class EditableText extends StatefulWidget {
  /// {@endtemplate}
  bool get selectionEnabled => enableInteractiveSelection;

+  /// {@template flutter.widgets.editableText.selectAllOnFocus}
+  /// Whether or not this field should select all text when gaining focus


Period at the end here and the next sentence.

justinmc · 2025-05-01T20:30:08Z

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

@@ -163,6 +163,7 @@ class TextFormField extends FormField<String> {
    Brightness? keyboardAppearance,
    EdgeInsets scrollPadding = const EdgeInsets.all(20.0),
    bool? enableInteractiveSelection,
+    bool? selectAllOnFocus,


And this one could have a default I think?

Yeah, having said that, it is not obvious that it defaults to defaultSelectAllOnFocus on line 287... I could put that in the comment, but I don't see how I can make defaultSelectAllOnFocus const... What are your thoughts?

I am merging this conversation and #163491 (comment)
I am taking away the default since it isn't obvious and making defaultSelectAllOnFocus private

Yeah, I think this ends up being like a lot of the other parameters here — the default is complicated, and the reader is left to look it up in the documentation of the corresponding field.

On this particular class and constructor, since this isn't a this.foo field parameter, that lookup is a bit more complicated than usual; but the constructor itself says what to do:

/// […] /// For documentation about the various parameters, see the [TextField] class /// and [TextField.new], the constructor. TextFormField({

and the [TextField.selectAllOnFocus] doc will have the answer.

gnprice

Thanks for the contribution! I agree this simple API, with a boolean, seems good. Small comments below.

gnprice · 2025-05-01T22:24:57Z

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

+  /// The default value for [selectAllOnFocus].
+  static bool get defaultSelectAllOnFocus {


This can stay private, right? It doesn't seem like API that's needed from outside this class.

gnprice · 2025-05-01T22:26:54Z

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

@@ -283,6 +284,7 @@ class TextFormField extends FormField<String> {
               keyboardAppearance: keyboardAppearance,
               enableInteractiveSelection:
                   enableInteractiveSelection ?? (!obscureText || !readOnly),
+               selectAllOnFocus: selectAllOnFocus ?? EditableText.defaultSelectAllOnFocus,


I guess it currently gets used here. But I think this can just pass through the value it has, whether that's null or otherwise — seems like that's cleanest anyway, by minimizing the number of details about EditableText that TextFormField needs to know.

gnprice · 2025-05-01T22:27:45Z

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

+  /// {@template flutter.widgets.editableText.selectAllOnFocus}
+  /// Whether or not this field should select all text when gaining focus
+  ///
+  /// By default this will select all text on web and desktop


Suggested change

/// By default this will select all text on web and desktop

/// Defaults to true on web and desktop platforms,

/// and false on mobile platforms.

gnprice · 2025-05-01T22:44:23Z

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

@@ -1798,6 +1800,13 @@ class EditableText extends StatefulWidget {
  /// {@endtemplate}
  bool get selectionEnabled => enableInteractiveSelection;

+  /// {@template flutter.widgets.editableText.selectAllOnFocus}
+  /// Whether or not this field should select all text when gaining focus


Suggested change

/// Whether or not this field should select all text when gaining focus

/// Whether this field should select all text when gaining focus.

///

/// When false, focusing this text field will leave its

/// existing text selection unchanged.

Fix grammer and clarify comments

camfrandsen · 2025-05-05T19:02:37Z

@gnprice @justinmc Thank you both again, I really appreciate the help (and opportunity) on this 😆

justinmc

LGTM 👍

justinmc · 2025-05-06T18:15:29Z

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

@@ -923,6 +924,7 @@ class EditableText extends StatefulWidget {
       ),
       assert(!obscureText || maxLines == 1, 'Obscured fields cannot be multiline.'),
       enableInteractiveSelection = enableInteractiveSelection ?? (!readOnly || !obscureText),
+       selectAllOnFocus = selectAllOnFocus ?? _defaultSelectAllOnFocus,


Can't this be done inline on line 885? this.selectAllOnFocus = _defaultSelectAllOnFocus.

gnprice

Thanks! LGTM.

gnprice · 2025-05-07T02:07:28Z

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

@@ -163,6 +163,7 @@ class TextFormField extends FormField<String> {
    Brightness? keyboardAppearance,
    EdgeInsets scrollPadding = const EdgeInsets.all(20.0),
    bool? enableInteractiveSelection,
+    bool? selectAllOnFocus,


Yeah, I think this ends up being like a lot of the other parameters here — the default is complicated, and the reader is left to look it up in the documentation of the corresponding field.

On this particular class and constructor, since this isn't a this.foo field parameter, that lookup is a bit more complicated than usual; but the constructor itself says what to do:

/// […] /// For documentation about the various parameters, see the [TextField] class /// and [TextField.new], the constructor. TextFormField({

and the [TextField.selectAllOnFocus] doc will have the answer.

add highlightAllOnFocus to text_field

92dc589

This allows overriding the default behavior of highlighting all the text on focus when using web or desktop

github-actions bot added a: text input Entering text in a text field or keyboard related problems framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. labels Feb 17, 2025

camfrandsen mentioned this pull request Feb 17, 2025

Add ability to disable highlighting text field on focus in text field on web/desktop #163399

Open

justinmc reviewed Feb 26, 2025

View reviewed changes

justinmc reviewed Mar 13, 2025

View reviewed changes

camfrandsen added 2 commits March 22, 2025 12:08

Replace highlightAllOnFocus with setCustomSelectionOnFocus

c8c0892

setCustomSelectionOnFocus allows developers to set the selection when the text field gets focus

Merge remote-tracking branch 'origin/master' into highlightAllOnFocus

443fc3a

Fix comment on SetCustomSelectionOnFocus

568907a

justinmc reviewed Apr 2, 2025

View reviewed changes

camfrandsen and others added 2 commits April 7, 2025 09:53

Use different selection in test so that it is more obviouls that the …

768e452

…selection changed Add missing period to document

Merge branch 'master' into highlightAllOnFocus

f76af66

justinmc reviewed Apr 11, 2025

View reviewed changes

github-actions bot added the f: cupertino flutter/packages/flutter/cupertino repository label Apr 15, 2025

camfrandsen force-pushed the highlightAllOnFocus branch from 8db6817 to e77c811 Compare April 15, 2025 17:41

Revert back to a bool (selectAllOnFocus)

9fea2b0

Defaults to true on web

camfrandsen force-pushed the highlightAllOnFocus branch from e77c811 to 9fea2b0 Compare April 15, 2025 20:05

justinmc reviewed Apr 24, 2025

View reviewed changes

Simplify logic for _adjustedSelectionWhenFocused

75094de

Fix comments now that selectAllOnFocus is not platform specific

dkwingsmt changed the title ~~Add Option to disable full selection on focus on TextField, TestFormField, and EditableText~~ Add Option to disable full selection on focus on TextField, TextFormField, and EditableText Apr 30, 2025

justinmc reviewed May 1, 2025

View reviewed changes

gnprice reviewed May 1, 2025

View reviewed changes

Make defaultSelectAllOnFocus private

6d09332

Fix grammer and clarify comments

justinmc approved these changes May 6, 2025

View reviewed changes

gnprice approved these changes May 7, 2025

View reviewed changes

	final bool shouldSelectAll =
	widget.selectionEnabled &&
	(kIsWeb \|\| isDesktop) &&
	!_isMultiline &&
	!_nextFocusChangeIsInternal &&
	!_justResumed;

		/// Whether or not this field should highlight all text when gaining focus on
		/// web or desktop.

		/// By default this will highlight the text field on web and desktop, and can
		/// only be turned off on those two platforms.

		/// The default value for [selectAllOnFocus].
		static bool get defaultSelectAllOnFocus {

	/// By default this will select all text on web and desktop
	/// Defaults to true on web and desktop platforms,
	/// and false on mobile platforms.

-  /// Whether or not this field should select all text when gaining focus
+  /// Whether this field should select all text when gaining focus.
+  ///
+  /// When false, focusing this text field will leave its
+  /// existing text selection unchanged.

Add Option to disable full selection on focus on TextField, TextFormField, and EditableText #163491

Are you sure you want to change the base?

Add Option to disable full selection on focus on TextField, TextFormField, and EditableText #163491

Conversation

camfrandsen commented Feb 17, 2025 • edited Loading

Pre-launch Checklist

justinmc left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

justinmc Feb 26, 2025 • edited Loading

Choose a reason for hiding this comment

camfrandsen commented Feb 28, 2025

justinmc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camfrandsen commented Mar 22, 2025

justinmc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camfrandsen commented Apr 7, 2025

justinmc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camfrandsen commented Apr 15, 2025

justinmc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

justinmc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gnprice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camfrandsen commented May 5, 2025

justinmc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gnprice left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

camfrandsen commented Feb 17, 2025 •

edited

Loading

justinmc left a comment •

edited

Loading

justinmc Feb 26, 2025 •

edited

Loading