rspec/rules/S7120/dart/rule.adoc

Widget constructors should have a https://api.flutter.dev/flutter/widgets/Widget/key.html[`key`] parameter, forwarded to the superclass constructor.

== Why is this an issue?

The https://api.flutter.dev/flutter/widgets/Widget/Widget.html[`Widget` constructor] takes a `key` as a named parameter. However, such a parameter is optional:

[source,dart]
----
class Widget {
  Widget({ Key? key }) { ...}
}
----

This means that widgets inheriting from it can be created without a `key` parameter.

[source,dart]
----
class MyWidget extends Widget {
  MyWidget() : super(); // No key parameter forwarded
}
----

The same applies to the https://api.flutter.dev/flutter/widgets/StatefulWidget-class.html[`StatefulWidget`] and the https://api.flutter.dev/flutter/widgets/StatelessWidget-class.html[`StatelessWidget`]. 

They both define constructors with an optional `key` parameter, which:

* is forwarded to the `Widget` constructor when specified
* is not forwarded when omitted

That results in a widget with a `null` key.

While this is not a problem in itself, it is a good practice to always provide a `key` parameter to widgets, as it can be useful for debugging, testing, and performance optimizations.

For example, when a widget needs to potentially be rebuilt, Flutter compares the new widget with the old one to determine what has changed. If the widgets have the same key, Flutter assumes that they are the same, and it will not perform the rebuild. This can be useful when building the widget is expensive, or when the it has a state that should be preserved across rebuilds.

Scenarios where keys are useful include preserving the scroll position of a list, the state of a form, or the content of an editing collection.

== How to fix it

Add a `key` parameter of type `Key` to each of the constructor of the widget, and forward it to the superclass constructor:

* either using a `super` parameter formal: `MyWidget({ this.key });`
* or forwarding explicitly: `MyWidget({ Key? key }) : super(key: key);`

=== Code examples

==== Noncompliant code example

[source,dart,diff-id=1,diff-type=noncompliant]
----
class MyWidget extends Widget {
  MyWidget() : super(); // Non compliant
}
----

==== Compliant solution

[source,dart,diff-id=1,diff-type=compliant]
----
class MyWidget extends Widget {
  MyWidget({ super.key });
}
----

==== Noncompliant code example

[source,dart,diff-id=2,diff-type=noncompliant]
----
class MyWidget extends Widget {
  final int widgetConfig;

  MyWidget(this.widgetConfig) : super(); // Non compliant
}
----

==== Compliant solution

[source,dart,diff-id=2,diff-type=compliant]
----
class MyWidget extends Widget {
  final int widgetConfig;

  MyWidget(this.widgetConfig, { Key? key }) : super(key: key);
}
----

== Resources

=== Documentation

* Dart Docs - https://dart.dev/tools/linter-rules/use_key_in_widget_constructors[Dart Linter rule - use_key_in_widget_constructors]
* Flutter API Reference - https://api.flutter.dev/flutter/widgets/Widget/Widget.html[Widget class - constructor]
* Flutter API Reference - https://api.flutter.dev/flutter/widgets/Widget/key.html[Widget class - key property]


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Constructors for public widgets should have a named 'key' parameter.

=== Highlighting

If the widget class has no constructor declarations in it: the identifier name of the widget class: e.g. `MyWidget` in `class MyWidget { ... }`.

If the widget class has constructors declarations in it: the identifier name of the constructor missing the `key` parameter: e.g. `MyWidget` in `MyWidget()`. If the constructor is named, only the name of the constructor is highlighted, and the class name is not: e.g. `named` in `MyWidget.named()`.

endif::env-github,rspecator-view[]