Annotations

@provider

Marks a class or function as a Riverpod provider. The generator creates the notifier, provider declaration, and accessor classes.

Class-based (async)

part 'todos_provider.craft.dart';

@provider
class Todos extends _$Todos {
  @override
  Future<List<Todo>> create() => api.fetchTodos();
}

Class-based (sync)

part 'counter_provider.craft.dart';

@provider
class Counter extends _$Counter {
  @override
  int create() => 0;
}

Functional (async)

part 'user_provider.craft.dart';

@provider
Future<User> user(Ref ref) => api.getUser();

Stream

part 'messages_provider.craft.dart';

@provider
Stream<List<Message>> messages(Ref ref) => api.messagesStream();

Return type determines provider type

Return type	Notifier base class	State type
T	StateDataNotifier	T (sync)
Future<T>	DataNotifier	DataState<T>
Stream<T>	DataNotifier	DataState<T>

---

@command

Marks an async method inside a @provider class as a side effect. Each command gets its own independent state.

@provider
class Notes extends _$Notes {
  @override
  Future<List<Note>> create() => repo.getNotes();

  @override
  @command
  @droppable
  Future<Note> addNote({required String title}) async {
    final note = await repo.addNote(title: title);
    reload();
    return note;
  }
}

See Side Effects for the full guide.

---

@keepAlive

Prevents the provider from being auto-disposed when no longer listened to.

@provider
@keepAlive
class Auth extends _$Auth {
  @override
  Future<AuthState> create() => checkAuth();
}

By default, all providers are auto-disposed. Use @keepAlive for state that should persist (auth, app settings, etc.).

---

@settable

Enables setState() on functional providers. Only works on functional providers — ignored on class-based providers.

@provider
@settable
NoteCategory categoryFilter(Ref ref) => NoteCategory.all;

See State Provider for the full guide.

---

@family

Creates parameterized providers. Use parameters in create() (class-based) or function parameters (functional).

Functional

part 'note_detail_provider.craft.dart';

@provider
Future<Note> noteDetail(Ref ref, {required String id}) {
  return repo.getNoteById(id);
}

Usage:

ref.noteDetailProvider(id: '123').watch()

Class-based

part 'user_profile_provider.craft.dart';

@provider
class UserProfile extends _$UserProfile {
  @override
  Future<Profile> create({required String userId}) {
    return api.getProfile(userId);
  }
}

Usage:

ref.userProfileProvider(userId: 'abc').watch()

---

Concurrency annotations

Used with @command to control behavior when a command is called while already running.

Annotation	Behavior
@droppable	Ignores new calls while busy
@restartable	Cancels the current execution, starts the new one
@sequential	Queues calls, processes one at a time
@concurrent	Allows multiple simultaneous executions

@override
@command
@restartable
Future<List<Result>> search({required String query}) => api.search(query);