# freezed 4.0.1
Code generation for immutable classes that has a simple syntax/API without compromising on the features.
## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add 'freezed:4.0.1'
```
Published: 2026-08-29T17:50:43.317002Z
Expected archive SHA-256: 541a82723c84298f3ca46a6c2186935aa21ad529ad1f1423d67af18040494f51
Available in cache; verification: upstream_checksum
## Direct dependencies
- analyzer: >=13.0.0 <15.0.0
- analyzer_buffer: ^0.3.3
- build: >=3.0.0 <5.0.0
- build_config: ^1.1.0
- collection: ^1.15.0
- dart_style: ^3.0.0
- freezed_annotation: 3.1.0
- json_annotation: ^4.8.0
- meta: ^1.9.1
- pub_semver: ^2.2.0
- source_gen: >=3.0.0 <5.0.0
## Package README (untrusted upstream documentation)
[English](https://github.com/rrousselGit/freezed/blob/master/packages/freezed/README.md) | [한국어](https://github.com/rrousselGit/freezed/blob/master/resources/translations/ko_KR/README.md) | [简体中文](https://github.com/rrousselGit/freezed/blob/master/resources/translations/zh_CN/README.md) | [日本語](https://github.com/rrousselGit/freezed/blob/master/resources/translations/ja_JP/README.md) | [Tiếng Việt](https://github.com/rrousselGit/freezed/blob/master/resources/translations/vi_VN/README.md)
[](https://pub.dartlang.org/packages/freezed)
[](https://flutter.dev/docs/development/packages-and-plugins/favorites)
Welcome to [Freezed], yet another code generator for data classes, tagged unions, nested classes and cloning.
# Migration to 3.0.0
To migrate from 2.0.0 to 3.0.0, see [changelog](https://github.com/rrousselGit/freezed/blob/master/packages/freezed/CHANGELOG.md#300---2025-02-25) and our [migration guide](https://github.com/rrousselGit/freezed/blob/master/packages/freezed/migration_guide.md).
# Motivation
Dart is awesome, but defining a "model" can be tedious. You have to:
- Define a constructor + properties
- Override `toString`, `operator ==`, `hashCode`
- Implement a `copyWith` method to clone the object
- Handle (de)serialization
Implementing all of this can take hundreds of lines, which are error-prone
and affect the readability of your model significantly.
Freezed tries to fix that by implementing most of this for you, allowing you
to focus on the definition of your model.
| Before | After |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|  |  |
# Index
- [Migration to 3.0.0](#migration-to-300)
- [Motivation](#motivation)
- [Index](#index)
- [How to use](#how-to-use)
- [Install](#install)
- [Disabling invalid_annotation_target warning and warning in generates files](#disabling-invalid_annotation_target-warning-and-warning-in-generates-files)
- [Run the generator](#run-the-generator)
- [Creating a Model using Freezed](#creating-a-model-using-freezed)
- [Primary constructors](#primary-constructors)
- [Adding getters and methods to our models](#adding-getters-and-methods-to-our-models)
- [Asserts](#asserts)
- [Default values](#default-values)
- [Non-constant default values](#non-constant-default-values)
- [Extending classes](#extending-classes)
- [Defining a mutable class instead of an immutable one](#defining-a-mutable-class-instead-of-an-immutable-one)
- [Allowing the mutation of Lists/Maps/Sets](#allowing-the-mutation-of-listsmapssets)
- [Classic classes](#classic-classes)
- [How copyWith works](#how-copywith-works)
- [Going further: Deep copy](#going-further-deep-copy)
- [Decorators and comments](#decorators-and-comments)
- [FromJson/ToJson](#fromjsontojson)
- [fromJSON - classes with multiple constructors](#fromjson---classes-with-multiple-constructors)
- [Deserializing generic classes](#deserializing-generic-classes)
- [Union types](#union-types)
- [Shared properties](#shared-properties)
- [Using pattern matching to read non-shared properties](#using-pattern-matching-to-read-non-shared-properties)
- [Mixins and Interfaces for individual classes for union types](#mixins-and-interfaces-for-individual-classes-for-union-types)
- [Ejecting an individual union case](#ejecting-an-individual-union-case)
- [(Legacy) Pattern matching utilities](#legacy-pattern-matching-utilities)
- [When](#when)
- [Map](#map)
- [Configurations](#configurations)
- [Changing the behavior for a specific model](#changing-the-behavior-for-a-specific-model)
- [Changing the behavior for the entire project](#changing-the-behavior-for-the-entire-project)
- [Utilities](#utilities)
- [IDE Extensions](#ide-extensions)
- [Freezed extension for VSCode](#freezed-extension-for-vscode)
- [Freezed extension for IntelliJ/Android Studio](#freezed-extension-for-intellijandroid-studio)
- [Linting](#linting)
- [Third-party tools](#third-party-tools)
- [DartJ](#dartj)
- [Sponsors](#sponsors)
# How to use
## Install
To use [Freezed], you will need your typical [build_runner]/code-generator setup.\
First, install [build_runner] and [Freezed] by adding them to your `pubspec.yaml` file:
For a Flutter project:
```console
flutter pub add \
dev:build_runner \
freezed_annotation \
dev:freezed
# if using freezed to generate fromJson/toJson, also add:
flutter pub add json_annotation dev:json_serializable
```
For a Dart project:
```console
dart pub add \
dev:build_runner \
freezed_annotation \
dev:freezed
# if using freezed to generate fromJson/toJson, also add:
dart pub add json_annotation dev:json_serializable
```
This installs three packages:
- [build_runner](https://pub.dev/packages/build_runner), the tool to run code-generators
- [freezed], the code generator
- [freezed_annotation](https://pub.dev/packages/freezed_annotation), a package containing annotations for [freezed].
### Disabling invalid_annotation_target warning and warning in generates files
If you plan on using [Freezed] in combination with `json_serializable`, recent
versions of `json_serializable` and `meta` may require you to disable the
`invalid_annotation_target` warning.
To do that, you can add the following to the `analysis_options.yaml` file
at the root of your project:
```yaml
analyzer:
errors:
invalid_annotation_target: ignore
```
## Run the generator
To run the code generator, execute the following command:
```
dart run build_runner watch -d
```
Note that like most code-generators, [Freezed] will need you to both import the annotation ([freezed_annotation])
and use the `part` keyword on the top of your files.
As such, a file that wants to use [Freezed] will start with:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'my_file.freezed.dart';
```
**CONSIDER** also importing `package:flutter/foundation.dart`.\
The reason being, importing `foundation.dart` also imports classes to make an
object nicely readable in Flutter's devtool.\
If you import `foundation.dart`, [Freezed] will automatically do it for you.
## Creating a Model using Freezed
Freezed offers two ways of creating data-classes:
- [Primary constructors](#primary-constructors) ; where you define a constructor and Freezed generates the associated fields.
This is simulating the [Primary Constructor](https://github.com/dart-lang/language/issues/2364) using `factory`.
- [Classic classes](#classic-classes), where you write a normal Dart class and Freezed only handles `toString/==/copyWith`
### Primary constructors
**Note**
As of Dart 3.13, primary constructors are a stable feature of Dart. This means
that you no longer need to use `freezed` to generate primary constructors.
But you can stick to using Freezed for ==/toString/etc:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'main.freezed.dart';
part 'main.g.dart';
@freezed
class Person({
required final String firstName,
required final String lastName,
required final int age,
required final DateTime birthDate,
}) with _$Person;
void main() {
var person = Person(
firstName: 'John',
lastName: 'Doe',
age: 42,
birthDate: DateTime(1978),
);
person = person.copyWith(age: 43);
}
```
---
Freezed implements Primary Constructors by relying on `factory` constructors.
The idea is, you define a `factory` and Freezed generates everything else:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
// required: associates our `main.dart` with the code generated by Freezed
part 'main.freezed.dart';
// optional: Since our Person class is serializable, we must add this line.
// But if Person was not serializable, we could skip it.
part 'main.g.dart';
@freezed
abstract class Person with _$Person {
const factory Person({
required String firstName,
required String lastName,
required int age,
}) = _Person;
factory Person.fromJson(Map json) => _$PersonFromJson(json);
}
```
The following snippet defines a model named `Person`:
- `Person` has 3 properties: `firstName`, `lastName` and `age`
- Because we are using `@freezed`, all of this class's properties are immutable.
- Since we defined a `fromJson`, this class is de/serializable.
Freezed will add a `toJson` method for us.
- Freezed will also automatically generate:
- a `copyWith` method, for cloning the object with different properties
- a `toString` override listing all the properties of the object
- an `operator ==` and `hashCode` override (since `Person` is immutable)
From this example, we can notice a few things:
- It is necessary to annotate our model with `@freezed` (or `@Freezed`/`@unfreezed`, more about that later).
This annotation is what tells Freezed to generate code for that class.
- We must also apply a mixin with the name of our class, prefixed by `_$`.
This mixin is what defines the various properties/methods of our object.
- When defining a constructor in a Freezed class, we should use the `factory` keyword
as showcased (`const` is optional).
The parameters of this constructor will be the list of all properties that this class contains.
Parameters **don't** have to be named and required. Feel free to use
positional optional parameters if you want!
#### Adding getters and methods to our models
Sometimes, you may want to manually define methods/properties in our classes.
But you will quickly notice that if you try to use primary constructors:
```dart
@freezed
abstract class Person with _$Person {
const factory Person(String name, {int? age}) = _Person;
void method() {
print('hello world');
}
}
```
then it will fail with the error `The non-abstract class _$_Person is missing implementations for these members:`.
For that to work, we need to define a private empty constructor. That will enable the generated code to _extend/subclass_ our class, instead of _implementing_ it (which is the default, and only inherits type, and not properties or methods):
```dart
@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');
}
}
```
#### Asserts
Dart does not allow adding `assert(...)` statements to a `factory` constructor.
As such, to add asserts to your Freezed classes, you will need the `@Assert` decorator:
```dart
@freezed
abstract class Person with _$Person {
@Assert('name.isNotEmpty', 'name cannot be empty')
const factory Person({required String name, int? age}) = _Person;
}
```
Alternatively, you can specify a `MyClass._()` constructor:
```dart
@freezed
abstract class Person with _$Person {
Person._({required this.name})
: assert(name.isNotEmpty, 'name cannot be empty');
factory Person({required String name, int? age}) = _Person;
final String name;
}
```
#### Default values
Similarly to asserts, Dart does not allow "redirecting factory constructors"
to specify default values.
As such, if you want to specify default values for your properties,
you will need the `@Default` annotation:
```dart
@freezed
abstract class Example with _$Example {
const factory Example([@Default(42) int value]) = _Example;
}
```
**NOTE**:\
If you are using serialization/deserialization, this will automatically add
a `@JsonKey(defaultValue: )` for you.
#### Non-constant default values
If using `@Default` is not enough, you have two options:
- Either stop using primary constructors. See [Classic Classes](#classic-classes)
- Add a `MyClass._()` constructor to initialize said value
The latter is particularly helpful when writing large models, as this doesn't require writing a lot of code just for one default values.
One example would be the following:
```dart
@freezed
sealed class Response with _$Response {
// We give "time" parameters a non-constant default
Response._({DateTime? time}) : time = time ?? DateTime.now();
// Constructors may enable passing parameters to ._();
factory Response.data(T value, {DateTime? time}) = ResponseData;
// If ._ parameters are named and optional, factory constructors are not required to specify it
factory Response.error(Object error) = ResponseError;
final DateTime time;
}
```
In this example, the field `time` is defaulting to `DateTime.now()`.
#### Extending classes
You may want to have your Freezed class extend another class.
Unfortunately, `factory` does not allow specifying `super(...)`.
As such, one workaround is to specify the `MyClass._()` again, similarly
to how we used it for non-constant default values. Here's an example:
```dart
class Subclass {
const Subclass.name(this.value);
final int value;
}
@freezed
abstract class MyFreezedClass extends Subclass with _$MyFreezedClass {
// We can receive parameters in this constructor, which we can use with `super.field`
const MyFreezedClass._(super.value) : super.name();
const factory MyFreezedClass(int value, /* other fields */) = _MyFreezedClass;
}
```
This syntax gives full control over inheritance.
Of course, you can also opt-out of `factory` constructors and write normal classes.
See [Classic Classes](#classic-classes).
In general, this workaround makes more sense for [Unions](#union-types), where
we have more than one `factory` constructor.
#### Defining a mutable class instead of an immutable one
So far, we've seen how to define a model where all of its properties are `final`;
but you may want to define mutable properties in your model.
Freezed supports this, by replacing the `@freezed` annotation with `@unfreezed`:
```dart
@unfreezed
abstract class Person with _$Person {
factory Person({
required String firstName,
required String lastName,
}) = _Person;
factory Person.fromJson(Map json) => _$PersonFromJson(json);
}
```
This defines a model mostly identical to our previous snippets, but with the following
differences:
- `firstName` and `lastName` are now mutable. As such, we can write:
```dart
void main() {
var person = Person(firstName: 'John', lastName: 'Smith');
person.firstName = 'Mona';
person.lastName = 'Lisa';
}
```
- `Person` no-longer has a custom ==/hashCode implementation:
```dart
void main() {
var john = Person(firstName: 'John', lastName: 'Smith');
var john2 = Person(firstName: 'John', lastName: 'Smith');
print(john == john2); // false
}
```
- Of course, since our `Person` class is mutable, it is no-longer possible
to instantiate it using `const`.
#### Allowing the mutation of Lists/Maps/Sets
By default when using `@freezed` (but not `@unfreezed`), properties of type `List`/`Map`/`Set`
are transformed to be immutable.
This means that writing the following will cause a runtime exception:
```dart
@freezed
abstract class Example with _$Example {
factory Example(List list) = _Example;
}
void main() {
var example = Example([]);
example.list.add(42); // throws because we are mutating a collection
}
```
That behavior can be disabled by writing:
```dart
@Freezed(makeCollectionsUnmodifiable: false)
abstract class Example with _$Example {
factory Example(List list) = _Example;
}
void main() {
var example = Example([]);
example.list.add(42); // OK
}
```
### Classic classes
Instead of primary constructors, you can write normal Dart classes.
In this scenario, write a typical constructor + fields combo as you normally would:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
// required: associates our `main.dart` with the code generated by Freezed
part 'main.freezed.dart';
// optional: Since our Person class is serializable, we must add this line.
// But if Person was not serializable, we could skip it.
part 'main.g.dart';
@freezed
@JsonSerializable()
class Person with _$Person {
const Person({
required this.firstName,
required this.lastName,
required this.age,
});
final String firstName;
final String lastName;
final int age;
factory Person.fromJson(Map json)
=> _$PersonFromJson(json);
Map toJson() => _$PersonToJson(this);
}
```
In this scenario, Freezed will generate `copyWith`/`toString`/`==`/`hashCode`,
but won't do anything related to JSON encoding (hence why you need to manually add `@JsonSerializable`).
This syntax has the benefit of enabling advanced constructor logic, such as
inheritance or non-constant default values.
## How copyWith works
As explained before, when defining a model using Freezed, then the code-generator
will automatically generate a `copyWith` method for us.
This method is used to clone an object with different values.
For example if we define:
```dart
@freezed
abstract class Person with _$Person {
factory Person(String name, int? age) = _Person;
}
```
Then we could write:
```dart
void main() {
var person = Person('Remi', 24);
// `age` not passed, its value is preserved
print(person.copyWith(name: 'Dash')); // Person(name: Dash, age: 24)
// `age` is set to `null`
print(person.copyWith(age: null)); // Person(name: Remi, age: null)
}
```
Notice Freezed supports `person.copyWith(age: null)`.
### Going further: Deep copy
While `copyWith` is very powerful in itself, it becomes inconvenient on more complex objects.
Consider the following classes:
```dart
@freezed
abstract class Company with _$Company {
const factory Company({String? name, required Director director}) = _Company;
}
@freezed
abstract class Director with _$Director {
const factory Director({String? name, Assistant? assistant}) = _Director;
}
@freezed
abstract class Assistant with _$Assistant {
const factory Assistant({String? name, int? age}) = _Assistant;
}
```
Then, from a reference on `Company`, we may want to perform changes on `Assistant`.\
For example, to change the `name` of an assistant, using `copyWith` we would have to write:
```dart
Company company;
Company newCompany = company.copyWith(
director: company.director.copyWith(
assistant: company.director.assistant.copyWith(
name: 'John Smith',
),
),
);
```
This _works_, but is relatively verbose with a lot of duplicates.\
This is where we could use [Freezed]'s "deep copy".
If a Freezed model contains properties that are also Freezed models, then
the code-generator will offer an alternate syntax to the previous example:
```dart
Company company;
Company newCompany = company.copyWith.director.assistant(name: 'John Smith');
```
This snippet will achieve strictly the same result as the previous snippet
(creating a new company with an updated assistant name), but no longer has duplicates.
Going deeper in this syntax, if instead, we wanted to change the director's name
then we could write:
```dart
Company company;
Company newCompany = company.copyWith.director(name: 'John Doe');
```
Overall, based on the definitions of `Company`/`Director`/`Assistant` mentioned above,
all the following "copy" syntaxes will work:
```dart
Company company;
company = company.copyWith(name: 'Google', director: Director(...));
company = company.copyWith.director(name: 'Larry', assistant: Assistant(...));
```
**Null consideration**
Some objects may also be `null`. For example, using our `Company` class,
then `Director`'s `assistant` may be `null`.
As such, writing:
```dart
Company company = Company(name: 'Google', director: Director(assistant: null));
Company newCompany = company.copyWith.director.assistant(name: 'John');
```
doesn't make sense.
We can't change the assistant's name if there is no assistant to begin with.
In that situation, `company.copyWith.director.assistant` will return `null`,
causing our code to fail to compile.
To fix it, we can use the `?.call` operator and write:
```dart
Company? newCompany = company.copyWith.director.assistant?.call(name: 'John');
```
## Decorators and comments
[Freezed] supports property and class level decorators/documentation by
decorating/documenting their respective parameter and constructor definition.
Consider:
```dart
@freezed
abstract class Person with _$Person {
const factory Person({
String? name,
int? age,
Gender? gender,
}) = _Person;
}
```
If you want to document `name`, you can do:
```dart
@freezed
abstract class Person with _$Person {
const factory Person({
/// The name of the user.
///
/// Must not be null
String? name,
int? age,
Gender? gender,
}) = _Person;
}
```
If you want to mark the property `gender` as `@deprecated`, then you can do:
```dart
@freezed
abstract class Person with _$Person {
const factory Person({
String? name,
int? age,
@deprecated Gender? gender,
}) = _Person;
}
```
This will deprecate both:
- The constructor
```dart
Person(gender: Gender.something); // gender is deprecated
```
- The generated class's constructor:
```dart
_Person(gender: Gender.something); // gender is deprecated
```
- the property:
```dart
Person person;
print(person.gender); // gender is deprecated
```
- the `copyWith` parameter:
```dart
Person person;
person.copyWith(gender: Gender.something); // gender is deprecated
```
Similarly, if you want to decorate the generated class you can decorate the
defining factory constructor.
As such, to deprecate `_Person`, you could do:
```dart
@freezed
abstract class Person with _$Person {
@deprecated
const factory Person({
String? name,
int? age,
Gender? gender,
}) = _Person;
}
```
## FromJson/ToJson
While [Freezed] will not generate your typical `fromJson`/`toJson` by itself, it knows
what [json_serializable] is.
Making a class compatible with [json_serializable] is very straightforward.
Consider this snippet:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'model.freezed.dart';
@freezed
sealed class Model with _$Model {
factory Model.first(String a) = First;
factory Model.second(int b, bool c) = Second;
}
```
The changes necessary to make it compatible with [json_serializable] consists of two lines:
- a new `part`: `part 'model.g.dart';`
- a new constructor on the targeted class: `factory Model.fromJson(Map json) => _$ModelFromJson(json);`
The end result is:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'model.freezed.dart';
part 'model.g.dart';
@freezed
sealed class Model with _$Model {
factory Model.first(String a) = First;
factory Model.second(int b, bool c) = Second;
factory Model.fromJson(Map json) => _$ModelFromJson(json);
}
```
Don't forget to add `json_serializable` to your `pubspec.yaml` file:
```yaml
dev_dependencies:
json_serializable:
```
That's it!\
With these changes, [Freezed] will automatically ask [json_serializable] to generate all the necessary
`fromJson`/`toJson`.
**Note**:
Freezed will only generate a fromJson if the factory is using `=>`.
### fromJSON - classes with multiple constructors
For classes with multiple constructors, [Freezed] will check the JSON response
for a string element called `runtimeType` and choose the constructor to use based
on its value. For example, given the following constructors:
```dart
@freezed
sealed class MyResponse with _$MyResponse {
const factory MyResponse(String a) = MyResponseData;
const factory MyResponse.special(String a, int b) = MyResponseSpecial;
const factory MyResponse.error(String message) = MyResponseError;
factory MyResponse.fromJson(Map json) => _$MyResponseFromJson(json);
}
```
Then [Freezed] will use each JSON object's `runtimeType` to choose the constructor as follows:
```json
[
{
"runtimeType": "default",
"a": "This JSON object will use constructor MyResponse()"
},
{
"runtimeType": "special",
"a": "This JSON object will use constructor MyResponse.special()",
"b": 42
},
{
"runtimeType": "error",
"message": "This JSON object will use constructor MyResponse.error()"
}
]
```
You can customize key and value with something different
using `@Freezed` and `@FreezedUnionValue` decorators:
```dart
@Freezed(unionKey: 'type', unionValueCase: FreezedUnionCase.pascal)
sealed class MyResponse with _$MyResponse {
const factory MyResponse(String a) = MyResponseData;
@FreezedUnionValue('SpecialCase')
const factory MyResponse.special(String a, int b) = MyResponseSpecial;
const factory MyResponse.error(String message) = MyResponseError;
factory MyResponse.fromJson(Map json) =>
_$MyResponseFromJson(json);
}
```
which would update the previous json to:
```json
[
{
"type": "Default",
"a": "This JSON object will use constructor MyResponse()"
},
{
"type": "SpecialCase",
"a": "This JSON object will use constructor MyResponse.special()",
"b": 42
},
{
"type": "Error",
"message": "This JSON object will use constructor MyResponse.error()"
}
]
```
If you want to customize key and value for all the classes, you can specify it inside your
`build.yaml` file, for example:
```yaml
targets:
$default:
builders:
freezed:
options:
union_key: type
union_value_case: pascal
```
If you don't control the JSON response, then you can implement a custom converter.
Your custom converter will need to implement its own logic for determining which
constructor to use.
```dart
class MyResponseConverter implements JsonConverter> {
const MyResponseConverter();
@override
MyResponse fromJson(Map json) {
// type data was already set (e.g. because we serialized it ourselves)
if (json['runtimeType'] != null) {
return MyResponse.fromJson(json);
}
// you need to find some condition to know which type it is. e.g. check the presence of some field in the json
if (isTypeData) {
return MyResponseData.fromJson(json);
} else if (isTypeSpecial) {
return MyResponseSpecial.fromJson(json);
} else if (isTypeError) {
return MyResponseError.fromJson(json);
} else {
throw Exception('Could not determine the constructor for mapping from JSON');
}
}
@override
Map toJson(MyResponse data) => data.toJson();
}
```
To then apply your custom converter pass the decorator to a constructor parameter.
```dart
@freezed
abstract class MyModel with _$MyModel {
const factory MyModel(@MyResponseConverter() MyResponse myResponse) = MyModelData;
factory MyModel.fromJson(Map json) => _$MyModelFromJson(json);
}
```
By doing this, json serializable will use `MyResponseConverter.fromJson()` and `MyResponseConverter.toJson()` to convert `MyResponse`.
You can also use a custom converter on a constructor parameter contained in a `List`.
```dart
@freezed
abstract class MyModel with _$MyModel {
const factory MyModel(@MyResponseConverter() List myResponse) = MyModelData;
factory MyModel.fromJson(Map json) => _$MyModelFromJson(json);
}
```
**Note**:
In order to serialize nested lists of freezed objects, you are supposed to either
specify a `@JsonSerializable(explicitToJson: true)` or change `explicit_to_json`
inside your `build.yaml` file ([see the documentation](https://github.com/google/json_serializable.dart/tree/master/json_serializable#build-configuration)).
### Deserializing generic classes
In order to de/serialize generic typed freezed objects, you can enable `genericArgumentFactories`.
All you need to do is to change the signature of the `fromJson` method and add `genericArgumentFactories: true` to the freezed configuration.
```dart
@Freezed(genericArgumentFactories: true)
sealed class ApiResponse with _$ApiResponse {
const factory ApiResponse.data(T data) = ApiResponseData;
const factory ApiResponse.error(String message) = ApiResponseError;
factory ApiResponse.fromJson(Map json, T Function(Object?) fromJsonT) => _$ApiResponseFromJson(json, fromJsonT);
}
```
Alternatively, you can enable `genericArgumentFactories` for the whole project by modifying your `build.yaml` file to include the following:
```yaml
targets:
$default:
builders:
freezed:
options:
generic_argument_factories: true
```
**What about `@JsonKey` annotation?**
All decorators passed to a constructor parameter are "copy-pasted" to the generated
property too.\
As such, you can write:
```dart
@freezed
abstract class Example with _$Example {
factory Example(@JsonKey(name: 'my_property') String myProperty) = _Example;
factory Example.fromJson(Map json) => _$ExampleFromJson(json);
}
```
**What about `@JsonSerializable` annotation?**
You can pass `@JsonSerializable` annotation by placing it over constructor e.g.:
```dart
@freezed
abstract class Example with _$Example {
@JsonSerializable(explicitToJson: true)
factory Example(@JsonKey(name: 'my_property') SomeOtherClass myProperty) = _Example;
factory Example.fromJson(Map json) => _$ExampleFromJson(json);
}
```
If you want to define some custom json_serializable flags for all the classes (e.g. `explicit_to_json` or `any_map`) you can do it via `build.yaml` file as described [here](https://pub.dev/packages/json_serializable#build-configuration).
See also the [decorators](#decorators-and-comments) section
## Union types
Coming from other languages, you may be used to features like "union types," "sealed classes," and pattern matching.
These are powerful tools in combination with a type system, but it isn't particularly ergonomic to use them in Dart.
But fear not, [Freezed] supports them, generating a few utilities to help you!
Long story short, in any Freezed class, you can write multiple constructors:
```dart
@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;
}
```
By doing this, our model now can be in different mutually exclusive states.
In particular, this snippet defines a model `Union`, and that model has 3 possible states:
- data
- loading
- error
Note how we gave meaningful names to the right hand of the factory constructors we defined.
They will come in handy later.
One thing you may also notice is that with this example, we can no longer write code such as:
```dart
void main() {
Union union = Union.data(42);
print(union.value); // compilation error: property value does not exist
}
```
We'll see why in the following section.
### Shared properties
When defining multiple constructors, you will lose the ability to read properties that are not common to all constructors:
For example, if you write:
```dart
@freezed
sealed class Example with _$Example {
const factory Example.person(String name, int age) = Person;
const factory Example.city(String name, int population) = City;
}
```
Then you will be unable to read `age` and `population` directly:
```dart
var example = Example.person('Remi', 24);
print(example.age); // does not compile!
```
On the other hand, you **can** read properties that are defined on all constructors.
For example, the `name` variable is common to both `Example.person` and `Example.city` constructors.
As such we can write:
```dart
var example = Example.person('Remi', 24);
print(example.name); // Remi
example = Example.city('London', 8900000);
print(example.name); // London
```
The same logic can be applied to `copyWith` too.
We can use `copyWith` with properties defined on all constructors:
```dart
var example = Example.person('Remi', 24);
print(example.copyWith(name: 'Dash')); // Example.person(name: Dash, age: 24)
example = Example.city('London', 8900000);
print(example.copyWith(name: 'Paris')); // Example.city(name: Paris, population: 8900000)
```
On the other hand, properties that are unique to a specific constructor aren't available:
```dart
var example = Example.person('Remi', 24);
example.copyWith(age: 42); // compilation error, parameter `age` does not exist
```
To solve this problem, we need check the state of our object using what we call "pattern matching".
### Using pattern matching to read non-shared properties
For this section, let's consider the following union:
```dart
@freezed
sealed class Example with _$Example {
const factory Example.person(String name, int age) = Person;
const factory Example.city(String name, int population) = City;
}
```
Let's see how we can use pattern matching to read the content of an `Example` instance.
For this, you should use Dart’s built-in pattern matching using `switch`:
```dart
switch (example) {
Person(:final name) => print('Person $name'),
City(:final population) => print('City ($population)'),
}
```
Alternatively, you could use an `if`-`case` statement:
```dart
if (example case Person(:final name)) {
print('Person $name');
} else if (example case City(:final population)) {
print('City ($population)');
}
```
You could also use `is`/`as` to cast an `Example` variable into either a `Person` or a `City`, but this is heavily discouraged. Use one of the other two options.
### Mixins and Interfaces for individual classes for union types
When you have multiple types in the same class you might want one of those
types to implement an interface or mixin a class. You can do that using the
`@Implements` or `@With` decorators respectively. In the following example
`City` implements `GeographicArea`.
```dart
abstract class GeographicArea {
int get population;
String get name;
}
@freezed
sealed class Example with _$Example {
const factory Example.person(String name, int age) = Person;
@Implements()
const factory Example.city(String name, int population) = City;
}
```
This also works for implementing or mixing in generic classes e.g.
`AdministrativeArea` except when the class has a generic type parameter
e.g. `AdministrativeArea`. In this case freezed will generate correct code
but dart will throw a load error on the annotation declaration when compiling.
To avoid this you should use the `@Implements.fromString` and
`@With.fromString` decorators as follows:
```dart
abstract class GeographicArea {}
abstract class House {}
abstract class Shop {}
abstract class AdministrativeArea {}
@freezed
sealed class Example with _$Example {
const factory Example.person(String name, int age) = Person;
@With.fromString('AdministrativeArea')
const factory Example.street(String name) = Street;
@With()
@Implements()
@Implements()
@Implements.fromString('AdministrativeArea')
const factory Example.city(String name, int population) = City;
}
```
**Note**: You need to make sure that you comply with the interface
requirements by implementing all the abstract members. If the interface
has no members or just fields, you can fulfill the interface contract by
adding them to the union type's constructor. Keep in mind that if
the interface defines a method or a getter, that you implement in the
class, you need to use the
[Adding getters and methods to our models](#adding-getters-and-methods-to-our-models) instructions.
**Note 2**: You cannot use `@With`/`@Implements` with freezed classes.
Freezed classes can neither be extended nor implemented.
### Ejecting an individual union case
To have fine-grained control over your models, Freezed offer the ability to manually write a subclass of a union.
Consider:
```dart
@freezed
sealed class Result with _$Result {
factory Result.data(T data) = ResultData;
factory Result.error(Object error) = ResultError;
}
```
Now, let's say we wanted to write `ResultData` ourselves. For that, simply
define a `ResultData` class in the same file:
```dart
@freezed
sealed class Result with _$Result {
factory Result.data(T data) = ResultData;
factory Result.error(Object error) = ResultError;
}
class ResultData implements Result {
// TODO: implement Result
}
```
Note that the extracted class can be a Freezed class too!
```dart
@freezed
sealed class Result with _$Result {
const Result._();
const factory Result.data(T data) = ResultData;
const factory Result.error(Object error) = ResultError;
}
// TODO maybe add some methods unique to ResultData
@freezed
abstract class ResultData extends Result with _$ResultData {
const factory ResultData(T data) = _ResultData;
const ResultData._() : super._();
}
```
#### (Legacy) Pattern matching utilities
> [!WARNING]
> As of Dart 3, Dart now has built-in pattern-matching using sealed classes.
> As such, you no-longer need to rely on Freezed's generated methods for pattern matching.
> Instead of using `when`/`map`, use the official Dart syntax.
>
> The references to `when`/`map` are kept for users who have yet to
> migrate to Dart 3.
> But in the long term, you should stop relying on them and migrate to `switch` expressions.
##### When
The [when] method is the equivalent to pattern matching with destructuring.
The prototype of the method depends on the constructors defined.
For example, with:
```dart
@freezed
sealed class Union with _$Union {
const factory Union(int value) = Data;
const factory Union.loading() = Loading;
const factory Union.error([String? message]) = ErrorDetails;
}
```
Then [when] will be:
```dart
var union = Union(42);
print(
union.when(
(int value) => 'Data $value',
loading: () => 'loading',
error: (String? message) => 'Error: $message',
),
); // Data 42
```
Whereas if we defined:
```dart
@freezed
sealed class Model with _$Model {
factory Model.first(String a) = First;
factory Model.second(int b, bool c) = Second;
}
```
Then [when] will be:
```dart
var model = Model.first('42');
print(
model.when(
first: (String a) => 'first $a',
second: (int b, bool c) => 'second $b $c'
),
); // first 42
```
Notice how each callback matches with a constructor's name and prototype.
##### Map
The [map] methods are equivalent to [when], but **without** destructuring.
Consider this class:
```dart
@freezed
sealed class Model with _$Model {
factory Model.first(String a) = First;
factory Model.second(int b, bool c) = Second;
}
```
With such class, while [when] will be:
```dart
var model = Model.first('42');
print(
model.when(
first: (String a) => 'first $a',
second: (int b, bool c) => 'second $b $c'
),
); // first 42
```
[map] will instead be:
```dart
var model = Model.first('42');
print(
model.map(
first: (First value) => 'first ${value.a}',
second: (Second value) => 'second ${value.b} ${value.c}'
),
); // first 42
```
This can be useful if you want to do complex operations, like [copyWith]/`toString` for example:
```dart
var model = Model.second(42, false)
print(
model.map(
first: (value) => value,
second: (value) => value.copyWith(c: true),
)
); // Model.second(b: 42, c: true)
```
## Configurations
Freezed offers various options to customize the generated code. To do so, there are two possibilities:
### Changing the behavior for a specific model
If you want to customize the generated code for only one specific class,
you can do so by using a different annotation:
```dart
@Freezed()
abstract class Person with _$Person {
factory Person(String name, int age) = _Person;
}
```
By doing so, you can now pass various parameters to `@Freezed` to change the output:
```dart
@Freezed(
// Disable the generation of copyWith/==
copyWith: false,
equal: false,
)
abstract class Person with _$Person {...}
```
To view all the possibilities, see the documentation of `@Freezed`:
### Changing the behavior for the entire project
Instead of applying your modification to a single class, you may want to apply it to
all Freezed models at the same time.
You can do so by customizing a file called `build.yaml`
This file is an optional configuration file that should be placed next to your `pubspec.yaml`:
```
my_project_folder/
pubspec.yaml
build.yaml
lib/
```
There, you will be able to change the same options as the options found in `@Freezed` (see above)
by writing:
```yaml
targets:
$default:
builders:
freezed:
options:
# Tells Freezed to format .freezed.dart files.
# This can significantly slow down code-generation.
# Disabling formatting will only work when opting into Dart 3.7 as a minimum
# in your project SDK constraints.
format: true
# Disable the generation of copyWith/== for the entire project
copy_with: false
equal: false
```
# Utilities
## IDE Extensions
### Freezed extension for VSCode
The [Freezed](https://marketplace.visualstudio.com/items?itemName=blaxou.freezed) extension might help you work faster with freezed. For example :
- Use Ctrl+Shift+B (Cmd+Shift+B on Mac) to quickly build using `build_runner`.
- Quickly generate a Freezed class by using Ctrl+Shift+P (Cmd+Shift+P on Mac)> `Generate Freezed class`.
### Freezed extension for IntelliJ/Android Studio
You can get Live Templates for boiler plate code [here](https://github.com/Tinhorn/freezed_intellij_live_templates).
Example:
- type **freezedClass** and press Tab to generate a freezed class
```dart
@freezed
class Demo with _$Demo {
}
```
- type **freezedFromJson** and press Tab to generate the fromJson method for json_serializable
```dart
factory Demo.fromJson(Map json) => _$DemoFromJson(json);
```
## Linting
You can add `freezed` specific linting rules that provide helpful utilities and catch common mistakes when creating `freezed` classes.
Add [`custom_lint`](https://pub.dev/packages/custom_lint) and `freezed_lint` to your `pubspec.yaml`:
```console
dart pub add dev:custom_lint
dart pub add dev:freezed_lint
```
Also add `custom_lint` to your `analysis_options.yaml`:
```yaml
analyzer:
plugins:
- custom_lint
```
## Third-party tools
This part contains community-made tools which integrate with Freezed.
### DartJ
[DartJ](https://dartj.web.app/#/) is Flutter application, made by [**@ttpho**](https://github.com/ttpho), which will generate the Freezed classes from a JSON payload.
Example:
## Sponsors
[build_runner]: https://pub.dev/packages/build_runner
[freezed]: https://pub.dartlang.org/packages/freezed
[freezed_annotation]: https://pub.dartlang.org/packages/freezed_annotation
[json_serializable]: https://pub.dev/packages/json_serializable
## Changelog
## 4.0.1 - 2026-08-29
- Removed the need for `@overrides` in class fields and primary constructors.
- Support analyzer 14.0.0
## 4.0.0 - 2026-08-22
- Fix `==`/`copyWith` when immutable collections are enabled yet non-factory constructors are used.
- Fix `(int,)` records incorrectly generated
- Support analyzer 13.0
- Support primary constructors
- _Breaking_: No-longer support `final` keyword inside constructor parameter. This is due to Dart 3.13 no-longer allowing this syntax.
This prevents `@unfreezed` from defining immutable fields.
## 4.0.0-dev.3 - 2026-06-13
- Fix `==`/`copyWith` when immutable collections are enabled yet non-factory constructors are used.
## 4.0.0-dev.2 - 2026-06-13
- Fix `(int,)` records incorrectly generated
## 4.0.0-dev.1 - 2026-06-11
- Support analyzer 13.0
- Support primary constructors
- _Breaking_: No-longer support `final` keyword inside constructor parameter. This is due to Dart 3.13 no-longer allowing this syntax.
This prevents `@unfreezed` from defining immutable fields.
## 3.2.6-dev.1 - 2026-04-23
Support analyzer 12.0
## 3.2.5 - 2026-02-03
Support analyzer 10.0
## 3.2.4
Support analyzer 9.0.0
## 3.2.3 - 2025-09-10
Broader the version range for `analyzer`/`source_gen`/`build`
## 3.2.2 - 2025-09-09
Bump `build`
## 3.2.1 - 2025-09-09
Support latest analyzer/source_gen
## 3.2.0 - 2025-07-18
- Use `build` 3.0.0-dev.
- Use `source_gen` 3.0.0-dev.
- Support Dart 3.8.0 and analyzer 7.5.9 as a minumum.
## 3.1.0 - 2025-07-02
- Added `when`/`map` back
- Stop writing `// dart format width=80` to the generated freezed files.
## 3.0.6 - 2025-04-05
Remove logs
## 3.0.5 - 2025-04-05
- Fix ==/hashCode when using inheritance.
The generated ==/hashCode now call `super == other` when necessary.
- Fix an issue with `Diagnosticable` and `toString`
- Fix ejecting union cases when more than one class is defined in a file
- Fix a copyWith bug when a constructor parameter has no matching property
- Fix null exception in some cases when using generic classes and copyWith
## 3.0.4 - 2025-03-16
- Update docs (thanks to @lishaduck)
- Support Dart 3.6.0 and analyzer 6.9.0 as a minimum.
## 3.0.3 - 2025-03-02
Update readme (thanks to @snapsl)
## 3.0.2 - 2025-02-27
- Fix various deep-copy bugs
- Throw when using `extends`/`with` but not specifying a `MyClass._()` constructor
- Throw when a Freezed class forgot to include `with _$MyClass`
- "Normal" classes shouldn't require `MyClass._()` when they define getters/methods/...
## 3.0.1 - 2025-02-27
Fix a bug with diagnosticable objects.
## 3.0.0 - 2025-02-25
### New: Mixed mode
Freezed 3.0 is about supporting a "mixed mode".
From now on, Freezed supports both the usual syntax:
```dart
@freezed
sealed class Usual with _$Usual {
factory Usual({int a}) = _Usual;
}
```
But also:
```dart
@freezed
class Usual with _$Usual {
Usual({this.a});
final int a;
}
```
This has multiple benefits:
- Simple classes don't need Freezed's "weird" syntax and can stay simple
- Unions can keep using the usual `factory` syntax
This also offers a way to use all constructor features, such as initializers
or `super()`:
```dart
class Base {
Base(String value);
}
@freezed
class Usual extends Base with _$Usual {
Usual({int? a}) a = a ?? 0, super('value');
final int a;
}
```
### New: Inheritance and non-constant default values.
When using Freezed, a common problem has always been the lack of `extends` support and non-constant default values.
Besides through "Mixed mode" mentioned above, Freezed now offers a way for `factory` constructors to specify non-constant defaults and a `super()`, by
relying on the `MyClass._()` constructor:
It also has another benefit:
Complex Unions now have a way to use Inheritance and non-constant default values,
by relying on a non-factory `MyClass._()` constructor.
For context:
Before, when a Freezed class specified a property or method,
it was required to specify a `MyClass._()` constructor:
```dart
@freezed
class Example with _$Example {
// Necessary for helloWorld() to work
Example._();
factory Example(String name) = _Example
void helloWorld() => print('Hello $name');
}
```
However, that `Example._()` constructor was required to have no parameter.
Starting Freezed 3.0, this constructor can accept any parameter.
Freezed will then pass its values from other `factory` constructors, based on name.
In short, this enables extending any class:
```dart
class Subclass {
Subclass.name(this.value);
final int value;
}
@freezed
class MyFreezedClass extends Subclass with _$MyFreezedClass {
// We can receive parameters in this constructor, which we can use with `super.field`
MyFreezedClass._(super.value): super.name();
factory MyFreezedClass(int value, /* other fields */) = _MyFreezedClass;
}
```
It also enables non-constant default values:
```dart
@freezed
sealed class Response with _$Response {
// We give "time" parameters a non-constant default
Response._({DateTime? time}) : time = time ?? DateTime.now();
// Constructors may enable passing parameters to ._();
factory Response.data(T value, {DateTime? time}) = ResponseData;
// If ._ parameters are named and optional, factory constructors are not required to specify it
factory Response.error(Object error) = ResponseError;
@override
final DateTime time;
}
```
### New: "Eject" union cases
Along with the mixed mode, it is also possible to eject
a "union" case, by having it point to a custom class.
Concretely, you can do:
```dart
@freezed
sealed class Result with _$Result {
Result._();
// Data does not exist, so Freezed will generate it as usual
factory Result.data(T data) = ResultData;
// We wrote a ResultError class in the same library, so Freezed won't do anything
factory Result.error(Object error) = ResultError;
}
// We manually wrote `ResultError`
class ResultError extends Result {
ResultError(this.error): super._();
final Object error;
}
```
This combines nicely with "Mixed mode" mentioned previously,
as extracted union cases can also be Freezed classes:
```dart
// Using freezed with a simple class:
@freezed
class ResultError extends Result {
ResultError(this.error): super._();
final Object error;
}
// Or using a factory:
@freezed
class ResultError extends Result {
ResultError._(): super._();
factory ResultError(Object error) = _ResultError;
}
```
This feature offers fine-grained control over every parts of your models.
**Note**:
Unfortunately, it is kind of required to "extend" the parent class (so here `extends Result`). This is because Dart doesn't support `sealed mixin class`, so you can't do
`with Result` instead.
### Other changes:
- **Breaking**: Removed `map/when` and variants. These have been discouraged since Dart got pattern matching.
- **Breaking**: Freezed classes should now either be `abstract`, `sealed`, or manually implements `_$MyClass`.
- When formatting is disabled (default), Freezed now generates `// dart format off`. This
prevents having to exclude generated file from formatting check in the CI.
- It is now possible to have a private constructor for unions:
```dart
@freezed
sealed class Result with _$Result {
// It wasn't possible to write _data before, but now is.
factory Result._data(T data) = ResultData;
factory Result.error(Object error) = ResultError;
}
```
## 2.5.8 - 2025-01-06
Support analyzer 7.0.0
## 2.5.7 - 2024-07-15
- `freezed_annotation` upgraded to `2.4.4`
## 2.5.6 - 2024-07-09
- Generate documentation for `copyWith` (thanks to @rekire)
## 2.5.5 - 2024-07-09
- Stop using `JsonKey(ignore: true)` in favour of `JsonKey(includeFromJson: false, includeToJson: false)`
(thanks to @lrsvmb)
- Require json_annotation ^6.8.0
## 2.5.4 - 2024-07-02
- Require Dart >=3.0.0
- Support latest `collection`
## 2.5.3 - 2024-05-14
- Support analyzer 6.5.0
## 2.5.2 - 2024-04-11
- Fixed `copyWith(value: null)` when using nullable generics
## 2.5.1 - 2024-04-08
- Fixed `@freezed` no-longer working inside `part of` files.
## 2.5.0
- Added `format: false` flag in the `build.yaml`, to disable formatting
in generated files.
This can significantly improve performance, but may require updating your
CI to not check that generated files are formatted.
- Fixed an `InconsistentAnalysisException`
## 2.4.8
- Fixed a performance problem
## 2.4.7 - 2024-02-04
- Fixed broken link in docs (thanks to @iDevOrz)
## 2.4.6 - 2023-12-15
- Have the `==` implementation use `Object` as parameter instead of `dynamic`
## 2.4.5 - 2023-10-10
Loosened `analyzer` version to support both ^5.13.0 and ^6.0.0 (thanks to @SunlightBro)
## 2.4.4 - 2023-10-10
Do not throw on unresolved annotations.
## 2.4.3 - 2023-09-27
- Fix lowercase warning on generated objects.
## 2.4.2 - 2023-08-03
- Support analyzer 6.0.0
## 2.4.1 - 2023-07-12
- `freezed_annotation` upgraded to `2.3.0`
## 2.4.0 - 2023-07-11
- Allow enabling/disabling all `when`/`map` variants at once (thanks to @gaetschwartz)
## 2.3.5 - 2023-06-05
- Fix regression in analyzer 5.13.0 (thanks to @SunlightBro)
## 2.3.4 - 2023-05-13
- Fix allow dollar ($) in recursive class names (thanks to @andreasgangso)
- Fix deprecated warning with analyzer 5.12.0 (thanks to @SunlightBro)
- Remove warning when marking a class as `abstract`
## 2.3.3
- Fixed an issue with the generated code when classes contains a `$` in
their property/constructor/class name (thanks to @medz)
## 2.3.2
Fix more issues with `copyWith`
## 2.3.1
Fix various issues with `copyWith`
## 2.3.0
- Union types now expose properties with the same name but different type on the
shared interface. (Thanks to @DevNico)
This allows doing:
```dart
@freezed
class Union with _$Union {
factory Union.first(int value) = _UnionFirst;
factory Union.second(double value) = _UnionSecond;
}
void main() {
Union union;
num value = union.value;
// No need for casting as "num" is the shared interface between int/double
}
```
- Fixes copyWith not working with `null` on some scenarios.
- Fixes a stackoverflow error when continuously passing unmodifiable collections as parameter to freezed classes
- fix: Deep copy now correctly handles cases where a property is a Freezed class with disabled `copyWith`
## 2.2.1
Upgrade analyzer
## 2.2.0
- The generated `copyWith` is now annotated by `@useResult` (thanks to @miDeb)
- Improved performance of `copyWith` (thanks to @miDeb)
- Improved type inference when using `mapOrNull`/`whenOrNull` (thanks to @DevNico)
- Re-introduced `@With.fromString` and `@Implements.fromString` to allow unions
to implement generic types. (thanks to @rorystephenson)
- fixes @Default for Strings containing (, [ or { (thanks to @hugobrancowb)
- fix Freezed incorrectly comparing primitives using `DeepCollectionEquality` (thanks to @knaeckeKami)
- fix image links (thanks to @SunlightBro)
## 2.1.1
- Bump Analyzer to 5.0.0
- Fix an issuee where Freezed fails to detect that the `Diagnosticable` API is available
## 2.1.0+1
Improve pub score
## 2.1.0
- Add support for de/serializing generic Freezed classes (Thanks to @TimWhiting)
- Fixed a StackOverflow error when defining circular `export`s (Thanks to @TimWhiting)
## 2.0.5
Increase minimum analyzer version.
## 2.0.4
Fixes a bug where using `@unfreezed` on unions somehow still generated immutable properties.
## 2.0.3+1
Update warning message when using abstract freezed classes
## 2.0.3
- fix: performance regression with ==/hashCode/copyWith due to immutable collections (#653)
- fix: build.yaml decoding crash
- fix: remove annotations on internal properties related to immutable collections (#659)
## 2.0.2
Fixed invalid generated code when defining nullable collections.
## 2.0.1
- Fixed a bug where the generated when/map methods were potentially invalid when
using default values
- Fixed a bug where when/map methods were generated even when not necessary
## 2.0.0
- **Breaking**: freezed_annotation no-longer exports the entire package:collection
- **Breaking**: Freezed no-longer generates `$MyClassTearOff`. This feature is now available in Dart
- **Breaking** Removed `@Freezed(maybeMap: )` & `@Freezed(maybeWhen: )` in favor of a separate:
```Dart
@Freezed(map: FreezedMap(...), when: FreezedWhenOptions(...))
```
- **Breaking**: Freezed now converts Lists/Maps/Sets into UnmodifiableListView/UnmodifiableMapView/UnmodifiableSetView.
This can be disabled for one class by specifying `@Freezed(makeCollectionsUnmodifiable: false)`.
Alternatively, this can be configured inside the `build.yaml` file
- Added parameters of `@Freezed` to customize the generated code.
This includes: fromJson, toJson, map, when, equal, toStringOverride, copyWith.
These parameters allow disabling code that would otherwise be generated.
It also allows forcing the generation even if it would otherwise not be generated.
- Feat: Add screaming snake union case type (#617) (thanks to @zbarbuto)
- Fix null exceptions in some cases when using typedefs (thanks to @smiLLe)
- Support analyzer 4.0.0
- Fix an issue with generic Freezed classes failing to compile when using `@With>()` #614
- Added `@unfreezed` as a variant to `@freezed`, for mutable classes
## 1.1.1
- Lints are now disabled inside generated files (requires Dart 2.15)
- Upgraded the analyzer version to 3.0.0
## 1.1.0
Added support for disabling the generation of `maybeMap`/`maybeWhen` (thanks to @Lyokone)
## 1.0.2+1
Updated the README
## 1.0.2
Fixed a regression with the ==/hashCode implementation generated for
classes with custom implementations of `List`/`Map`/... (see https://github.com/rrousselGit/freezed/issues/561)
## 1.0.1
Fixed an issue where some `build.yaml` options were not properly considered.
This includes changing where the generated files should be placed. (Thanks to @sperochon)
## 1.0.0
Freezed is now stable
This release also:
- reverted an involuntary change of how union types were de/serialized, breaking
existing code.
- fixed an issue with generic typedefs (thanks to @SunlightBro #552)
- fixed a potential null exception
## 0.15.1+1
- Fixed a bug where the generated code for serializable unions with a base class was invalid
## 0.15.1
- The union key is no longer passed `json_serializable` when deserializing avoid the case of being an `unrecognized_key` in some cases.
- Updated dependencies
- Increased minimum Dart SDK required to 2.14.0
- Fixed an issue where classes with a $ in their name could cause Freezed to fail (Thanks to @comigor #542)
- When using typedefs, the generated code now tries to use the typedef too
if possible, instead of the aliased type (Thanks to @Norbert515 #536).
- Added support for custom ==/hashCode implementation (Thanks to @casvanluijtelaa #526)
- When writing a custom `toJson` function, it will now always take precedence over
the default implementation generated by Freezed.
## 0.15.0+1
Fixed the generated `hashCode` not compiling for objects with a large number
of properties. (#531)
## 0.15.0
- **Breaking** Changed the syntax for `@With` and `@Implements` to use a generic annotation.
Before:
```dart
@With(MyClass)
@With.fromString('Generic')
```
After:
```dart
@With()
@With>()
```
- Fixed an issue with fromJson tear-offs not allowing `Object?` as map value. (#520)
- Optimized the generated implementation of `hashCode` and `==`
- Fixed an issue when `MyClass
](https://flutter.dev/docs/development/packages-and-plugins/favorites)
Welcome to [Freezed], yet another code generator for data classes, tagged unions, nested classes and cloning.
# Migration to 3.0.0
To migrate from 2.0.0 to 3.0.0, see [changelog](https://github.com/rrousselGit/freezed/blob/master/packages/freezed/CHANGELOG.md#300---2025-02-25) and our [migration guide](https://github.com/rrousselGit/freezed/blob/master/packages/freezed/migration_guide.md).
# Motivation
Dart is awesome, but defining a "model" can be tedious. You have to:
- Define a constructor + properties
- Override `toString`, `operator ==`, `hashCode`
- Implement a `copyWith` method to clone the object
- Handle (de)serialization
Implementing all of this can take hundreds of lines, which are error-prone
and affect the readability of your model significantly.
Freezed tries to fix that by implementing most of this for you, allowing you
to focus on the definition of your model.
| Before | After |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|  |  |
# Index
- [Migration to 3.0.0](#migration-to-300)
- [Motivation](#motivation)
- [Index](#index)
- [How to use](#how-to-use)
- [Install](#install)
- [Disabling invalid_annotation_target warning and warning in generates files](#disabling-invalid_annotation_target-warning-and-warning-in-generates-files)
- [Run the generator](#run-the-generator)
- [Creating a Model using Freezed](#creating-a-model-using-freezed)
- [Primary constructors](#primary-constructors)
- [Adding getters and methods to our models](#adding-getters-and-methods-to-our-models)
- [Asserts](#asserts)
- [Default values](#default-values)
- [Non-constant default values](#non-constant-default-values)
- [Extending classes](#extending-classes)
- [Defining a mutable class instead of an immutable one](#defining-a-mutable-class-instead-of-an-immutable-one)
- [Allowing the mutation of Lists/Maps/Sets](#allowing-the-mutation-of-listsmapssets)
- [Classic classes](#classic-classes)
- [How copyWith works](#how-copywith-works)
- [Going further: Deep copy](#going-further-deep-copy)
- [Decorators and comments](#decorators-and-comments)
- [FromJson/ToJson](#fromjsontojson)
- [fromJSON - classes with multiple constructors](#fromjson---classes-with-multiple-constructors)
- [Deserializing generic classes](#deserializing-generic-classes)
- [Union types](#union-types)
- [Shared properties](#shared-properties)
- [Using pattern matching to read non-shared properties](#using-pattern-matching-to-read-non-shared-properties)
- [Mixins and Interfaces for individual classes for union types](#mixins-and-interfaces-for-individual-classes-for-union-types)
- [Ejecting an individual union case](#ejecting-an-individual-union-case)
- [(Legacy) Pattern matching utilities](#legacy-pattern-matching-utilities)
- [When](#when)
- [Map](#map)
- [Configurations](#configurations)
- [Changing the behavior for a specific model](#changing-the-behavior-for-a-specific-model)
- [Changing the behavior for the entire project](#changing-the-behavior-for-the-entire-project)
- [Utilities](#utilities)
- [IDE Extensions](#ide-extensions)
- [Freezed extension for VSCode](#freezed-extension-for-vscode)
- [Freezed extension for IntelliJ/Android Studio](#freezed-extension-for-intellijandroid-studio)
- [Linting](#linting)
- [Third-party tools](#third-party-tools)
- [DartJ](#dartj)
- [Sponsors](#sponsors)
# How to use
## Install
To use [Freezed], you will need your typical [build_runner]/code-generator setup.\
First, install [build_runner] and [Freezed] by adding them to your `pubspec.yaml` file:
For a Flutter project:
```console
flutter pub add \
dev:build_runner \
freezed_annotation \
dev:freezed
# if using freezed to generate fromJson/toJson, also add:
flutter pub add json_annotation dev:json_serializable
```
For a Dart project:
```console
dart pub add \
dev:build_runner \
freezed_annotation \
dev:freezed
# if using freezed to generate fromJson/toJson, also add:
dart pub add json_annotation dev:json_serializable
```
This installs three packages:
- [build_runner](https://pub.dev/packages/build_runner), the tool to run code-generators
- [freezed], the code generator
- [freezed_annotation](https://pub.dev/packages/freezed_annotation), a package containing annotations for [freezed].
### Disabling invalid_annotation_target warning and warning in generates files
If you plan on using [Freezed] in combination with `json_serializable`, recent
versions of `json_serializable` and `meta` may require you to disable the
`invalid_annotation_target` warning.
To do that, you can add the following to the `analysis_options.yaml` file
at the root of your project:
```yaml
analyzer:
errors:
invalid_annotation_target: ignore
```
## Run the generator
To run the code generator, execute the following command:
```
dart run build_runner watch -d
```
Note that like most code-generators, [Freezed] will need you to both import the annotation ([freezed_annotation])
and use the `part` keyword on the top of your files.
As such, a file that wants to use [Freezed] will start with:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'my_file.freezed.dart';
```
**CONSIDER** also importing `package:flutter/foundation.dart`.\
The reason being, importing `foundation.dart` also imports classes to make an
object nicely readable in Flutter's devtool.\
If you import `foundation.dart`, [Freezed] will automatically do it for you.
## Creating a Model using Freezed
Freezed offers two ways of creating data-classes:
- [Primary constructors](#primary-constructors) ; where you define a constructor and Freezed generates the associated fields.
This is simulating the [Primary Constructor](https://github.com/dart-lang/language/issues/2364) using `factory`.
- [Classic classes](#classic-classes), where you write a normal Dart class and Freezed only handles `toString/==/copyWith`
### Primary constructors
**Note**
As of Dart 3.13, primary constructors are a stable feature of Dart. This means
that you no longer need to use `freezed` to generate primary constructors.
But you can stick to using Freezed for ==/toString/etc:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'main.freezed.dart';
part 'main.g.dart';
@freezed
class Person({
required final String firstName,
required final String lastName,
required final int age,
required final DateTime birthDate,
}) with _$Person;
void main() {
var person = Person(
firstName: 'John',
lastName: 'Doe',
age: 42,
birthDate: DateTime(1978),
);
person = person.copyWith(age: 43);
}
```
---
Freezed implements Primary Constructors by relying on `factory` constructors.
The idea is, you define a `factory` and Freezed generates everything else:
```dart
import 'package:freezed_annotation/freezed_annotation.dart';
// required: associates our `main.dart` with the code generated by Freezed
part 'main.freezed.dart';
// optional: Since our Person class is serializable, we must add this line.
// But if Person was not serializable, we could skip it.
part 'main.g.dart';
@freezed
abstract class Person with _$Person {
const factory Person({
required String firstName,
required String lastName,
required int age,
}) = _Person;
factory Person.fromJson(Map