Naming Conventions

The following naming conventions are simply recommendations and are completely optional. Feel free to use whatever naming conventions you prefer. You may find some of the examples/documentation do not follow the naming conventions mainly for simplicity/conciseness. These conventions are strongly recommended for large projects with multiple developers.

Event Conventions

Events should be named in the past tense because events are things that have already occurred from the bloc’s perspective.

Anatomy

BlocSubject + Noun (optional) + Verb (event)

Initial load events should follow the convention: BlocSubject + Started

Note

The base event class should be name: BlocSubject + Event.

Examples

✅ Good

counter_event.dart

sealed class CounterEvent {}
final class CounterStarted extends CounterEvent {}
final class CounterIncrementPressed extends CounterEvent {}
final class CounterDecrementPressed extends CounterEvent {}
final class CounterIncrementRetried extends CounterEvent {}

❌ Bad

counter_event.dart

sealed class CounterEvent {}
final class Initial extends CounterEvent {}
final class CounterInitialized extends CounterEvent {}
final class Increment extends CounterEvent {}
final class DoIncrement extends CounterEvent {}
final class IncrementCounter extends CounterEvent {}

State Conventions

States should be nouns because a state is just a snapshot at a particular point in time. There are two common ways to represent state: using subclasses or using a single class.

Anatomy

Subclasses

BlocSubject + Verb (action) + State

When representing the state as multiple subclasses State should be one of the following:

Initial | Success | Failure | InProgress

Note

Initial states should follow the convention: BlocSubject + Initial.

Single Class

BlocSubject + State

When representing the state as a single base class an enum named BlocSubject + Status should be used to represent the status of the state:

initial | success | failure | loading.

Note

The base state class should always be named: BlocSubject + State.

Examples

✅ Good

Subclasses

counter_state.dart

sealed class CounterState {}
final class CounterInitial extends CounterState {}
final class CounterLoadInProgress extends CounterState {}
final class CounterLoadSuccess extends CounterState {}
final class CounterLoadFailure extends CounterState {}

Single Class

counter_state.dart

enum CounterStatus { initial, loading, success, failure }
final class CounterState {
  const CounterState({this.status = CounterStatus.initial});
  final CounterStatus status;
}

❌ Bad

counter_state.dart

sealed class CounterState {}
final class Initial extends CounterState {}
final class Loading extends CounterState {}
final class Success extends CounterState {}
final class Succeeded extends CounterState {}
final class Loaded extends CounterState {}
final class Failure extends CounterState {}
final class Failed extends CounterState {}