Equatable

When extending Equatable, do not pass properties to the super constructor. Instead, override the props getter to return a list of the properties that should be used for equality comparison. This ensures that equality logic is explicitly defined and reduces errors caused by forgetting to pass values to the superclass.

class Person extends Equatable {
  const Person(this.name);

  final String name;

  @override
  List<Object> get props => [name];
}

To enable value-based equality for a class, extend Equatable and override the props getter. The props list should contain all the member variables that define the object's equality.

Important: Equatable is designed to work only with immutable objects. All member variables used in props must be final.

import 'package:equatable/equatable.dart';

class Person extends Equatable {
  const Person(this.name);

  final String name;

  @override
  List<Object> get props => [name];
}

To use Equatable in your project, add it to your pubspec.yaml dependencies and run the install command.

dependencies:
  equatable: ^2.0.0

# For Dart projects
pub get

# For Flutter projects
flutter packages get

To measure the performance of equality comparisons using package:equatable, follow these steps in the benchmarks directory:

1. Install the necessary dependencies using dart pub get.
2. Execute the benchmark suite using dart run main.dart.

Because properties are now defined via the props getter rather than the constructor, you can use const constructors in your classes. Using const constructors is highly recommended as it provides significant performance improvements.

class MySubClass extends MyClass {
  const MySubClass(this.data);

  final int data;
  
  @override
  List<Object> get props => [data];
}

If your class already extends another superclass, you cannot extend Equatable. Instead, use Equatable as a mixin to gain equality comparison capabilities.

class EquatableDateTime extends DateTime with Equatable {
  EquatableDateTime(
    int year, [int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0,]
  ) : super(year, month, day, hour, minute, second, millisecond, microsecond);

  @override
  List<Object> get props => [year, month, day, hour, minute, second, millisecond, microsecond];
}

You do not need to add the @immutable decorator to classes that extend Equatable. Equatable enforces immutability internally, so the decorator is redundant and can be omitted.

// Instead of this:
@immutable
class Person extends Equatable { ... }

// Use this:
class Person extends Equatable { ... }

You can set a global default for stringify using EquatableConfig.stringify.

Precedence: A local override of stringify within a specific class will always take precedence over this global configuration.

Default Behavior: EquatableConfig.stringify defaults to true in debug mode and false in release mode.

EquatableConfig.stringify = true;

You can include nullable properties in your props list by changing the return type of the props getter to List<Object?>.

import 'package:equatable/equatable.dart';

class Person extends Equatable {
  const Person(this.name, [this.age]);

  final String name;
  final int? age;

  @override
  List<Object?> get props => [name, age];
}

By default, toString() on an Equatable object returns only the type name (e.g., Person). To include the values of the properties in the string representation (e.g., Person(Bob)), override the stringify getter to return true.

import 'package:equatable/equatable.dart';

class Person extends Equatable {
  const Person(this.name);

  final String name;

  @override
  List<Object> get props => [name];

  @override
  bool get stringify => true;
}

You can control the global stringify behavior for all Equatable instances using the EquatableConfig class.

When stringify is enabled, toString implementations for Equatable objects will include the values of the properties in props. This is useful for debugging.

Precedence Rules:

• If you override stringify on a specific Equatable instance, that local value takes precedence over the global EquatableConfig.stringify setting.
• By default, stringify is true in debug mode and false in release mode.

To change the global behavior, set EquatableConfig.stringify to true or false.

import 'package:equatable/equatable.dart';

// Enable stringify globally
EquatableConfig.stringify = true;

// Disable stringify globally
EquatableConfig.stringify = false;