provider

When upgrading from version 3.x.0 to 4.0.0, several breaking changes must be addressed:

Parameter Changes

• initialBuilder is replaced by create.
• builder in proxy providers is replaced by update.
• builder in classic providers is replaced by create.

Lazy Loading

New create and update callbacks are lazy-loaded by default, meaning they are only called when the value is first read. To disable this behavior, set lazy: false.

FutureProvider(
  create: (_) async => doSomeHttpRequest(),
  lazy: false,
  child: ...
)

Renamed Classes and Interfaces

• ProviderNotFoundError is now ProviderNotFoundException.
• SingleChildCloneableWidget has been replaced by SingleChildWidget.
• DelegateWidget and its family have been removed. For custom providers, use direct subclasses of InheritedProvider or an existing provider.

Selector Behavior

Selector now performs deeper comparisons for collections. To revert to a standard equality check, use the shouldRebuild parameter.

Selector<Selected, Consumed>(
  shouldRebuild: (previous, next) => previous == next,
  builder: (context, next) => ...,
)

To create and manage the lifecycle (creation, listening, and disposal) of a new object, use the default constructor of a provider.

Important Rules:

• CREATE the object inside the create callback.
• DO NOT use .value constructors to create new objects; this can lead to unwanted side effects like premature disposal.
• DO NOT pass variables that change over time directly into the create callback, as the object will not be updated when those variables change. Use ProxyProvider for this instead.
• By default, create and update callbacks are lazy. They are only called when the value is requested at least once. Set lazy: false to compute the value immediately.

// CORRECT: Create a new object
Provider(
  create: (_) => MyModel(),
  child: ...
)

// INCORRECT: Using .value to create a new object
ChangeNotifierProvider.value(
  value: MyModel(),
  child: ...
)

// Eager loading (disabling lazy behavior)
MyProvider(
  create: (_) => Something(),
  lazy: false,
)

To create and expose a new object, use the default constructor of a provider with the create callback.

Important Guidelines:

• DO create new objects inside the create callback.
• DON'T use the .value constructor to create new objects; this can lead to unwanted side effects.
• DON'T pass variables that change over time directly into the create callback, as the object will not be updated when those variables change. Use ProxyProvider instead.

By default, create and update calls are lazy. The callback will not be executed until the value is requested at least once. You can disable this by setting lazy: false.

// DO: Create a new object inside create
Provider(
  create: (_) => MyModel(),
  child: ...
)

// DON'T: Use .value to create a new object
ChangeNotifierProvider.value(
  value: MyModel(),
  child: ...
)

// Disable lazy loading
MyProvider(
  create: (_) => Something(),
  lazy: false,
)

ProxyProvider allows you to create a new object that depends on another provider. When the dependency changes, the ProxyProvider will update its own value.

There are different variations:

• ProxyProvider, ProxyProvider2, ProxyProvider3, etc.: The number indicates how many other providers the ProxyProvider depends on.
• ProxyProvider vs ChangeNotifierProxyProvider vs ListenableProxyProvider: They function similarly, but instead of passing a result to a standard Provider, ChangeNotifierProxyProvider passes its value to a ChangeNotifierProvider.

Widget build(BuildContext context) {
  return MultiProvider(
    providers: [
      ChangeNotifierProvider(create: (_) => Counter()),
      ProxyProvider<Counter, Translations>(
        update: (_, counter, __) => Translations(counter.value),
      ),
    ],
    child: Foo(),
  );
}

class Translations {
  const Translations(this._value);

  final int _value;

  String get title => 'You clicked $_value times';
}