view_model library

A comprehensive ViewModel framework for Flutter applications.

This library provides a robust, scalable solution for state management in Flutter applications using the ViewModel pattern. It offers automatic lifecycle management, dependency tracking, and seamless integration with Flutter's widget system.

Quick Start

// 1. Define a ViewModel
class CounterViewModel extends ViewModel {
  int count = 0;
  void increment() => update(() => count++);
}

// 2. Create a Spec
final counterSpec = ViewModelSpec<CounterViewModel>(
  builder: () => CounterViewModel(),
);

// 3. Use in a Widget
class CounterPage extends StatefulWidget {
  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage>
    with ViewModelStateMixin {
  @override
  Widget build(BuildContext context) {
    final vm = viewModelBinding.watch(counterSpec);
    return ElevatedButton(
      onPressed: vm.increment,
      child: Text('Count: ${vm.count}'),
    );
  }
}

The viewModelBinding Accessor

viewModelBinding is your gateway to ViewModels:

Method Description
viewModelBinding.watch(spec) Get VM and rebuild on changes
viewModelBinding.read(spec) Get VM without rebuilding
viewModelBinding.watchCached<T>(key:) Cached VM with rebuilds
viewModelBinding.readCached<T>(key:) Cached VM, no rebuilds
viewModelBinding.listen(spec, onChanged:) Side effects, auto-dispose

Core Features

  • Automatic Lifecycle Management: ViewModels are automatically created, cached, and disposed based on widget lifecycle.
  • Instance Reuse: Share a single ViewModel instance across multiple widgets using keys or tags.
  • Value-level Rebuilds: Optimize performance by rebuilding only the widgets that depend on specific state values.
  • Stateful ViewModel: Manage immutable state with StateViewModel<S> and update it using setState(newState).
  • Dependency Injection: Decouple ViewModels from widgets and from each other.
  • DevTools Extension: Monitor and debug ViewModels in real-time with the Flutter DevTools extension.

Classes

AppPauseProvider
A ViewModelBindingPauseProvider that signals pause/resume based on the application's lifecycle state (AppLifecycleState).
AutoDisposeController
Controller for managing automatic disposal of resources.
CachedViewModelBuilder<T extends ViewModel>
Listens to and uses a ViewModel that already exists in the cache.
ChangeNotifierViewModel
A ViewModel implementation that extends Flutter's ChangeNotifier.
Expression
Marker type to carry a code expression string in annotations. The generator will unwrap Expr(code) and emit code as an expression inside builder closures, instead of a string literal.
GenSpec
Annotation to mark a ViewModel for spec code generation. Each annotated class will receive a generated ViewModelSpec variable in a .vm.dart part file.
InstanceArg
Arguments for ViewModel instance creation and identification.
ObservableValue<T>
A class that holds a value and can be observed by an ObserverBuilder.
ObserverBuilder<T>
A widget that listens to an ObservableValue and rebuilds whenever the value changes.
ObserverBuilder2<T1, T2>
A widget that listens to two ObservableValues and rebuilds whenever either value changes.
ObserverBuilder3<T1, T2, T3>
A widget that listens to three ObservableValues and rebuilds whenever any value changes.
PageRoutePauseProvider
A ViewModelBindingPauseProvider that uses RouteAware to determine pause state based on route navigation events (push, pop).
StateViewModel<T>
Abstract base class for ViewModels that manage state of type T.
StateViewModelValueWatcher<T>
A widget that listens to a StateViewModel and rebuilds itself when the selected parts of the state change.
TickerModePauseProvider
A ViewModelBindingPauseProvider that pauses/resumes based on TickerMode.
Vef
(Deprecated) Use ViewModelBinding instead.
ViewModel
Base mixin class for all ViewModels in the application.
ViewModelBinding
Core abstraction for managing ViewModel lifecycle and dependency injection.
ViewModelBindingInterface
Interface that exposes helpers to access ViewModels from widgets.
ViewModelBindingPauseProvider
BinderVisibleListener controls manual pause/resume for a page/state.
ViewModelBuilder<T extends ViewModel>
A convenient widget that does not require mixing ViewModelStateMixin into State.
ViewModelConfig
Global configuration for ViewModel behavior.
ViewModelFactory<T>
Abstract factory interface for creating ViewModel instances.
ViewModelLifecycle
Abstract interface for observing ViewModel lifecycle events.
ViewModelProvider<T extends ViewModel>
(Deprecated) Use ViewModelSpec instead.
ViewModelSpec<T extends ViewModel>
A simple, argument-less specification for creating a ViewModel. Provides builder and optional cache identifiers (key and tag). Use key to reuse the same instance for identical key+tag.
ViewModelSpecWithArg<VM extends ViewModel, A>
A specification for creating a ViewModel from an argument. The cache identifiers are computed from the argument.
ViewModelSpecWithArg2<VM extends ViewModel, A, B>
ViewModelSpecWithArg3<VM extends ViewModel, A, B, C>
ViewModelSpecWithArg4<VM extends ViewModel, A, B, C, D>

Mixins

ViewModelStatelessMixin
Stateless integration for ViewModel access from widgets.
ViewModelStateMixin<T extends StatefulWidget>
Mixin that integrates ViewModels with Flutter's State lifecycle.

Constants

genSpec → const GenSpec
Shorthand constant for GenSpec.