Flutter Key Lints

A Flutter custom lint package to enforce proper widget key usage for better Flutter application performance.

Why Keys Matter

Keys in Flutter are essential for:

1. Widget Reconciliation: Help Flutter distinguish between widget instances during rebuilds
2. State Preservation: Ensure widget state is maintained when widgets change position
3. Performance Optimization: Reduce unnecessary widget rebuilds
4. Animation: Enable smooth transitions between widget states

Installation

Add to your pubspec.yaml:

dev_dependencies:
  custom_lint: ^0.7.5
  flutter_key_lints: ^0.1.0

Configure in your analysis_options.yaml:

analyzer:
  plugins:
    - custom_lint

custom_lint:
  rules:
    - require_widget_key: true
    - list_item_key: true
    - appropriate_key_type: true
    - animation_key: true
    - performance_impact: true

Usage

Run custom lint to identify widgets missing keys:

dart run custom_lint

Rule Details

The package provides several rules to enforce best practices for widget keys:

1. require_widget_key

Flags widgets that should have keys but don't:

❌ Incorrect (missing key):

ListView(
  children: [
    ListTile(
      title: Text('Item 1'),
    ),
  ],
);

✅ Correct (with key):

ListView(
  children: [
    ListTile(
      key: ValueKey('item-1'),
      title: Text('Item 1'),
    ),
  ],
);

2. list_item_key

Specifically targets list items in ListView.builder, GridView.builder, etc., to ensure they have keys:

❌ Incorrect (missing key in list item):

ListView.builder(
  itemBuilder: (context, index) => ListTile(
    title: Text('Item $index'),
  ),
);

✅ Correct (with key):

ListView.builder(
  itemBuilder: (context, index) => ListTile(
    key: ValueKey(index),
    title: Text('Item $index'),
  ),
);

3. appropriate_key_type

Enforces the use of appropriate key types in different scenarios:

❌ Incorrect (overuse of GlobalKey):

// GlobalKey shouldn't be used unless needed for state access
Container(key: GlobalKey());

❌ Incorrect (raw Key usage):

// Raw Key constructor should be avoided
Container(key: Key('my-key'));

✅ Correct (appropriate key types):

// ValueKey for value-based identification
Container(key: ValueKey('container-1'));

// UniqueKey for truly unique instances
Container(key: UniqueKey());

// GlobalKey when state access is needed
final formKey = GlobalKey<FormState>();
Form(key: formKey, child: Container());

4. animation_key

Enforces the use of keys in animation widgets to prevent flickering and state loss:

❌ Incorrect (missing key for animation):

AnimatedContainer(
  duration: Duration(milliseconds: 300),
  color: isActive ? Colors.blue : Colors.grey,
  width: isActive ? 100 : 50,
); // Missing key

✅ Correct (with key for animation):

AnimatedContainer(
  key: ValueKey('my-animated-container'),
  duration: Duration(milliseconds: 300),
  color: isActive ? Colors.blue : Colors.grey,
  width: isActive ? 100 : 50,
);

5. performance_impact

Analyzes the potential performance impact of missing keys and provides severity levels:

❌ Critical Impact (high performance penalty):

ListView.builder(
  itemBuilder: (context, index) => ListTile(
    // No key results in complete list rebuilds
    title: Text('Item $index'),
  ),
);

❌ High Impact (significant performance penalty):

// Conditional widget without key causes state loss
if (isLoggedIn) {
  return UserDashboard();
} else {
  return LoginScreen();
}

✅ With Performance Analysis (showing the fix):

// Conditional widget with key preserves state
if (isLoggedIn) {
  return UserDashboard(key: ValueKey('dashboard'));
} else {
  return LoginScreen(key: ValueKey('login'));
}

Customizing Rules

You can customize rule behavior in your analysis_options.yaml:

custom_lint:
  rules:
    # Enable/disable specific rules
    - require_widget_key: true
    - list_item_key: true
    - appropriate_key_type: true
    - animation_key: true
    - performance_impact: true
    
    # Custom configuration for require_widget_key
    # Override the default exempt widget list
    require_widget_key:
      exempt_widgets: 
        - "SizedBox"
        - "Divider"
        - "Padding"
        - "Container"  # Add your own exemptions

Exempt Widgets

Some widgets don't require keys by default:

• Layout widgets (SizedBox, Divider, Padding, etc.)
• Decoration widgets (Opacity, Transform, etc.)
• Inherited widgets

Best Practices

1. Always use keys for items in lists, grids, or any reorderable content
2. Use keys when conditionally rendering widgets
3. Choose appropriate key types:
   • ValueKey: For value-based identification
   • UniqueKey: For truly unique instances
   • GlobalKey: When you need to access the widget's state

Known Issues & Workarounds

If you encounter compatibility issues between custom_lint and analyzer versions:

1. Pin versions: Ensure compatible analyzer and custom_lint versions
2. Manual review: Check list items and conditionally rendered widgets
3. Use IDE linting: VS Code/Android Studio Flutter plugins also help identify key issues

License

MIT (c) Jordan M. Adler 2025

Additional information

This package is designed to help Flutter developers improve their code quality by enforcing proper widget key usage. Keys are often overlooked but can significantly impact performance and state management.

Contributing

Contributions are welcome! Here's how you can help:

1. Report issues: If you find a bug or have a feature request, please open an issue
2. Submit pull requests: Feel free to improve the package or add new lint rules
3. Share feedback: Let us know how this package helps your development workflow

Running Tests

To run the tests for this package:

flutter test

Documentation

For more in-depth information about widget keys in Flutter:

• Widget Keys Guide - Comprehensive guide to understanding and using keys
• Widget Keys Cheatsheet - Quick reference for proper key usage
• Rules Reference - Detailed information about each lint rule
• Contributing Guide - How to contribute to the project
• Troubleshooting - Solutions to common issues

Additional documentation can be found in the doc directory.