Compose State: A Robust State Management Library for Flutter

Compose State is a comprehensive, highly-engineered state management library for Flutter. It is designed to handle almost every aspect of application state with a strong focus on robustness, performance, and developer control.

Its core philosophy is to provide a granular, reactive system inspired by frameworks like Jetpack Compose and SolidJS, but built idiomatically for Dart and Flutter.

Core Principles

Granular Reactivity: Build your UI from fine-grained, reactive state primitives (MutableState, DerivedState). Only the widgets that depend on a piece of state will rebuild when it changes.
Robustness & Resiliency: With built-in error handling, recovery strategies, and a circuit breaker, you can build applications that are resilient to failure.
Transactional Integrity: Batch multiple state changes into a single, atomic update. This prevents inconsistent UI states and ensures predictable updates.
Developer-First: Provides out-of-the-box solutions for common patterns (ApiState, PersistableState), along with powerful debugging tools, to reduce boilerplate and improve maintainability.

Quickstart: A Simple Counter

Let's build a simple counter to see how easy it is to get started.

1. Define Your State

First, define a piece of state. We'll use mutableStateOf to create a MutableState, which is a state that we can write to.

// Create a global state variable for our counter.
final counter = mutableStateOf(0);

2. Build Your UI

Next, use the StateBuilder widget to listen to your state and rebuild your UI whenever the state changes.

import 'package:flutter/material.dart';
import 'package:compose_state/compose_state.dart';

void main() {
  runApp(const MyApp());
}

// Create a global state variable for our counter.
final counter = mutableStateOf(0);

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Compose State Counter')),
        body: Center(
          // StateBuilder listens to any state used inside its builder
          child: StateBuilder(
            builder: (context) {
              return Text(
                // Read the value of the counter.
                // StateBuilder will automatically subscribe to changes.
                'Count: ${counter.value}',
                style: Theme.of(context).textTheme.headlineMedium,
              );
            },
          ),
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () {
            // Update the value. Any listening StateBuilder will rebuild.
            counter.value++;
          },
          child: const Icon(Icons.add),
        ),
      ),
    );
  }
}

That's it! The StateBuilder is smart enough to detect that you used counter.value and will automatically rebuild itself when the counter's value changes.

Next Steps

Ready to learn more? Dive into our documentation: