Freezed Documentation

If you need to define a class where properties can be modified after instantiation, replace the @freezed annotation with @unfreezed.

Note that @unfreezed classes:

• Have mutable properties.
• Do not implement == or hashCode (equality is based on object identity).
• Cannot be instantiated using const.

@unfreezed
abstract class Person with _$Person {
  factory Person({
    required String firstName,
    required String lastName,
  }) = _Person;

  factory Person.fromJson(Map<String, Object?> json)
      => _$PersonFromJson(json);
}

Freezed generates a copyWith method to create new instances with updated values.

For nested Freezed models, you can use Deep Copy syntax to avoid redundant boilerplate. Instead of nesting multiple copyWith calls, you can chain the properties: instance.copyWith.property1.property2(field: value).

Handling Nulls in Deep Copy: If a nested property might be null, use the ?.call operator to prevent compilation errors when attempting to access a property on a null object.

By default, Freezed classes using primary constructors are implemented by a generated class. If you try to add manual methods or getters, you will get a compilation error because the generated class is missing those members.

To fix this, define a private empty constructor const ClassName._();. This tells Freezed to make the generated class extend your class instead of just implementing it, allowing your manual members to be inherited.

Example

@freezed
abstract class Person with _$Person {
  // Added constructor. Must not have any parameter
  const Person._();

  const factory Person(String name, {int? age}) = _Person;

  void method() {
    print('hello world');
  }
}

When using union types, you can directly access properties that are defined in all constructors. Properties that are unique to only one constructor cannot be accessed directly on the base class and will cause a compilation error.

Example of shared properties:

@freezed
sealed class Example with _$Example {
  const factory Example.person(String name, int age) = Person;
  const factory Example.city(String name, int population) = City;
}

var example = Example.person('Remi', 24);
print(example.name); // Works because 'name' is in both constructors

Freezed allows you to define models that can exist in multiple mutually exclusive states by defining multiple factory constructors. This is useful for representing states like data, loading, and error.

Note for Dart 3+ users: Since Dart 3 introduced native sealed classes and pattern matching, it is recommended to use the official Dart switch syntax instead of Freezed's generated when or map methods. However, Freezed's methods are still available for legacy support.

@freezed
sealed class Union with _$Union {
  const factory Union.data(int value) = Data;
  const factory Union.loading() = Loading;
  const factory Union.error([String? message]) = Error;
}

Freezed allows you to define Union types (similar to sealed classes or sum types) by providing multiple constructors for a single class. This is useful for representing mutually exclusive states like Data, Loading, and Error.

If you are using Dart 3, it is highly recommended to use the sealed keyword when defining your Union class to enable native pattern matching.

@freezed
sealed class Union with _$Union {
  const factory Union.data(int value) = Data;
  const factory Union.loading() = Loading;
  const factory Union.error([String? message]) = Error;
}

Freezed provides a copyWith method to create a new instance of a class with modified values.

Standard copyWith

Useful for simple updates. If a value is not provided to copyWith, the existing value is preserved. Freezed also supports setting values to null via copyWith(field: null).

Deep Copy

For nested Freezed models, instead of nesting multiple copyWith calls, you can use the deep copy syntax: model.copyWith.property.subProperty(field: value).

Handling Nulls in Deep Copy: If a nested property might be null, use the ?.call operator to prevent compilation errors when attempting to access a property on a null object.

Freezed automatically generates a copyWith method for your models. This method allows you to create a new instance of an object with specific properties updated while keeping the rest of the values unchanged.

Crucially, Freezed supports setting properties to null using copyWith. If you pass a value to a parameter, it updates; if you omit it, the original value is preserved; and if you explicitly pass null, the property is set to null in the new instance.

@freezed
abstract class Person with _$Person {
  factory Person(String name, int? age) = _Person;
}

void main() {
  var person = Person('Remi', 24);

  // `age` is not provided, so it is preserved.
  print(person.copyWith(name: 'Dash')); // Person(name: Dash, age: 24)

  // `age` is explicitly set to `null`.
  print(person.copyWith(age: null)); // Person(name: Remi, age: null)
}