Skip to content

Commit 78d4f12

Browse files
authored
[material_ui] Document that TextField.decoration is merged with InputDecorationTheme (#12493)
`TextField.decoration`'s dartdoc describes what the decoration draws, but never mentions that the value passed here is *combined* with the ambient `InputDecorationTheme` rather than replacing it. `TextField` builds its effective decoration with `InputDecoration.applyDefaults` (`packages/material_ui/lib/src/text_field.dart`), and `applyDefaults` only substitutes properties that are null on the incoming `InputDecoration` — including `border: border ?? theme.border` (`packages/material_ui/lib/src/input_decorator.dart`). So a theme-provided border survives an `InputDecoration` that simply omits one, which is surprising if you read the property docs alone. That confusion is what flutter/flutter#159629 reports. This adds a paragraph to the `decoration` property documenting the merge and pointing at the explicit opt-out (`InputBorder.none`). This covers the documentation half of flutter/flutter#159629. The issue also proposes a `mergeWithTheme`-style flag on `InputDecoration`; that is an API proposal and is deliberately left out of this PR, so the issue should stay open. Originally opened against `flutter/flutter` as flutter/flutter#191260, and moved here after the code-freeze bot pointed out that Material changes now belong in `material_ui`. *Documentation-only change; no behavior change and no new tests.*
1 parent b0abd88 commit 78d4f12

2 files changed

Lines changed: 13 additions & 0 deletions

File tree

‎packages/material_ui/lib/src/text_field.dart‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -448,6 +448,15 @@ class TextField extends StatefulWidget {
448448
/// By default, draws a horizontal line under the text field but can be
449449
/// configured to show an icon, label, hint text, and error text.
450450
///
451+
/// This decoration does not replace the ambient [InputDecorationTheme].
452+
/// Instead, it is merged with it by [InputDecoration.applyDefaults]. Only the
453+
/// properties that are left null here take their value from the
454+
/// [InputDecorationThemeData] returned by [InputDecorationTheme.of], which in
455+
/// turn defaults to [ThemeData.inputDecorationTheme]. So, for example, when
456+
/// the theme specifies a border, passing an [InputDecoration] that leaves
457+
/// [InputDecoration.border] null does not remove that border; pass
458+
/// [InputBorder.none] to opt out of it explicitly.
459+
///
451460
/// Specify null to remove the decoration entirely (including the
452461
/// extra padding introduced by the decoration to save space for the labels).
453462
final InputDecoration? decoration;
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
changelog: |
2+
- Documents that `TextField.decoration` is merged with the ambient
3+
`InputDecorationTheme` rather than replacing it.
4+
version: patch

0 commit comments

Comments
 (0)