From 92b8fa33f3afff9d2e388960e48171667dec7662 Mon Sep 17 00:00:00 2001 From: Chun-Heng Tai Date: Wed, 28 May 2025 11:26:33 -0700 Subject: [PATCH 1/5] Add radio widget migration guide --- src/content/release/breaking-changes/index.md | 2 + .../breaking-changes/radio-api-redesign.md | 237 ++++++++++++++++++ 2 files changed, 239 insertions(+) create mode 100644 src/content/release/breaking-changes/radio-api-redesign.md diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index e52f3cbb5c9..08f8f659aca 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -42,10 +42,12 @@ They're sorted by release and listed in alphabetical order: ### Not yet released to stable +* [Redesigned the Radio Widget][] * [Removed semantics elevation and thickness][] * [Deprecate `TextField.canRequestFocus`][] * [Stop generating `AssetManifest.json`][] +[Redesigned the Radio Widget]: /release/breaking-changes/radio-api-redesign [Removed semantics elevation and thickness]: /release/breaking-changes/remove-semantics-elevation-and-thickness [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json diff --git a/src/content/release/breaking-changes/radio-api-redesign.md b/src/content/release/breaking-changes/radio-api-redesign.md new file mode 100644 index 00000000000..aafd8bb6eb5 --- /dev/null +++ b/src/content/release/breaking-changes/radio-api-redesign.md @@ -0,0 +1,237 @@ +--- +title: `Redesigned the Radio Widget` +description: >- + Changes to the Radio widget +--- + +## Summary + +Introduced the `RadioGroup` widget to centralize `groupValue` management and the `onChanged` +callback for a set of `Radio` widgets. As a result, the individual `Radio.groupValue` and +`Radio.onChanged` properties have been deprecated. + +## Context + +To meet APG (ARIA Practices Guide) requirements for keyboard navigation and semantic properties in +radio button groups, Flutter needed a dedicated radio group concept. Introducing a wrapper widget, +RadioGroup, provides this out-of-the-box support. This change also presented an opportunity to +simplify the API for individual Radio widgets. + +## Description of change + +Deprecated `Radio.onChanged`, `Radio.groupValue`, `CupertinoRadio.onChanged`, +`CupertinoRadio.groupValue`, `RadioListTile.groupValue`, and `RadioListTile.onChanged`. + +## Migration guide + +If you are using these properties, you can refactor them with `RadioGroup` + +### Case 1: trivial case + +Code before migration: + +```dart +Widget build(BuildContext context) { + return Column( + children: [ + Radio( + value: 0, + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, + ), + Radio( + value: 2, + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, + ), + ], + ); +} +``` + +Code after migration: + +```dart +Widget build(BuildContext context) { + return RadioGroup( + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, + child: Column( + children: [ + Radio(value: 0), + Radio(value: 2), + ], + ), + ); +} +``` + +### Case 2: disabled radio + +Code before migration: + +```dart +Widget build(BuildContext context) { + return Column( + children: [ + Radio( + value: 0, + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, + ), + Radio( + value: 2, + groupValue: _groupValue, + onChanged: null, // disabled + ), + ], + ); +} +``` + +Code after migration: + +```dart +Widget build(BuildContext context) { + return RadioGroup( + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, + child: Column( + children: [ + Radio(value: 0), + Radio(value: 2, enabled: false), + ], + ), + ); +} +``` + +### Case 3: mixed group or multi-selection + +Code before migration: + +```dart +Widget build(BuildContext context) { + return Column( + children: [ + Radio( + value: 1, + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, // disabled + ), + Radio( + value: 'a', + groupValue: _stringValue, + onChanged: (String? value) { + setState(() { + _stringValue = value; + }); + }, + ), + Radio( + value: 'b', + groupValue: _stringValue, + onChanged: (String? value) { + setState(() { + _stringValue = value; + }); + }, + ), + Radio( + value: 2, + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, // disabled + ), + ], + ); +} +``` + +Code after migration: + +```dart +Widget build(BuildContext context) { + return RadioGroup( + groupValue: _groupValue, + onChanged: (int? value) { + setState(() { + _groupValue = value; + }); + }, + child: Column( + children: [ + Radio(value: 1), + RadioGroup( + child: Column( + children: [ + Radio(value: 'a'), + Radio(value: 'b'), + ] + ), + ), + Radio(value: 2), + ], + ), + ); +} +``` + +## Timeline + +Landed in version: Not yet
+In stable release: Not yet + +## References + +* [`APG`][] + +API documentation: + +* [`Radio`][] +* [`CupertinoRadio`][] +* [`RadioListTile`][] +* [`RadioGroup`][] + +Relevant issue: + +* [Issue 113562][] + +Relevant PR: + +* [PR 168161][] + +[`APG`]: https://www.w3.org/WAI/ARIA/apg/patterns/radio +[`Radio`]: {{site.api}}/flutter/material/Radio-class.html +[`RadioListTile`]: {{site.api}}/flutter/material/RadioListTile-class.html +[`CupertinoRadio`]: {{site.api}}/flutter/cupertino/CupertinoRadio-class.html +[`RadioGroup`]: {{site.api}}/flutter/widgets/RadioGroup-class.html +[Issue 113562]: {{site.repo.flutter}}/issues/113562 +[PR 168161]: {{site.repo.flutter}}/pull/168161 From 1ec770d78bca7459420983e36392a13d57cf73df Mon Sep 17 00:00:00 2001 From: Chun-Heng Tai Date: Wed, 28 May 2025 12:01:48 -0700 Subject: [PATCH 2/5] fix format --- src/content/release/breaking-changes/radio-api-redesign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/radio-api-redesign.md b/src/content/release/breaking-changes/radio-api-redesign.md index aafd8bb6eb5..41b699fb240 100644 --- a/src/content/release/breaking-changes/radio-api-redesign.md +++ b/src/content/release/breaking-changes/radio-api-redesign.md @@ -1,5 +1,5 @@ --- -title: `Redesigned the Radio Widget` +title: Redesigned the Radio Widget description: >- Changes to the Radio widget --- From d71519334621dac5ee70f76355bea5eecd88b6dd Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 28 May 2025 16:51:29 -0700 Subject: [PATCH 3/5] Update src/content/release/breaking-changes/radio-api-redesign.md --- .../release/breaking-changes/radio-api-redesign.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/release/breaking-changes/radio-api-redesign.md b/src/content/release/breaking-changes/radio-api-redesign.md index 41b699fb240..65cb208a5ea 100644 --- a/src/content/release/breaking-changes/radio-api-redesign.md +++ b/src/content/release/breaking-changes/radio-api-redesign.md @@ -12,10 +12,10 @@ callback for a set of `Radio` widgets. As a result, the individual `Radio.groupV ## Context -To meet APG (ARIA Practices Guide) requirements for keyboard navigation and semantic properties in -radio button groups, Flutter needed a dedicated radio group concept. Introducing a wrapper widget, -RadioGroup, provides this out-of-the-box support. This change also presented an opportunity to -simplify the API for individual Radio widgets. +To meet APG (ARIA Practices Guide) requirements for keyboard navigation and +semantic properties in radio button groups, Flutter needed a dedicated radio group concept. +Introducing a wrapper widget, `RadioGroup`, provides this out-of-the-box support. +This change also presented an opportunity to simplify the API for individual `Radio` widgets. ## Description of change From 51a3e073c1cd949bf8999d7aec978f8318198d93 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 28 May 2025 16:51:36 -0700 Subject: [PATCH 4/5] Update src/content/release/breaking-changes/radio-api-redesign.md --- src/content/release/breaking-changes/radio-api-redesign.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/radio-api-redesign.md b/src/content/release/breaking-changes/radio-api-redesign.md index 65cb208a5ea..1c1f0789f36 100644 --- a/src/content/release/breaking-changes/radio-api-redesign.md +++ b/src/content/release/breaking-changes/radio-api-redesign.md @@ -24,7 +24,7 @@ Deprecated `Radio.onChanged`, `Radio.groupValue`, `CupertinoRadio.onChanged`, ## Migration guide -If you are using these properties, you can refactor them with `RadioGroup` +If you are using these properties, you can refactor them with `RadioGroup`. ### Case 1: trivial case From 672dd2183d3eee5cde5a4fb67038b58ec81c6274 Mon Sep 17 00:00:00 2001 From: "Shams Zakhour (ignore Sfshaza)" <44418985+sfshaza2@users.noreply.github.com> Date: Wed, 28 May 2025 16:51:45 -0700 Subject: [PATCH 5/5] Update src/content/release/breaking-changes/radio-api-redesign.md --- .../release/breaking-changes/radio-api-redesign.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/content/release/breaking-changes/radio-api-redesign.md b/src/content/release/breaking-changes/radio-api-redesign.md index 1c1f0789f36..bf7379e4538 100644 --- a/src/content/release/breaking-changes/radio-api-redesign.md +++ b/src/content/release/breaking-changes/radio-api-redesign.md @@ -19,8 +19,13 @@ This change also presented an opportunity to simplify the API for individual `Ra ## Description of change -Deprecated `Radio.onChanged`, `Radio.groupValue`, `CupertinoRadio.onChanged`, -`CupertinoRadio.groupValue`, `RadioListTile.groupValue`, and `RadioListTile.onChanged`. +The following API is deprecated: +* `Radio.onChanged` +* `Radio.groupValue` +* `CupertinoRadio.onChanged` +* `CupertinoRadio.groupValue` +* `RadioListTile.groupValue` +* `RadioListTile.onChanged`. ## Migration guide