> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# BLoC & Data

> Configure data fetching with RequestBuilders, provide custom BLoC instances, and listen to state changes.

> [accordion] AI Integration Quick Reference
>
> | Field | Value |
> | - | - |
> | Package | `cometchat_chat_uikit` |
> | Import | `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';` |
> | Purpose | Configure data fetching with RequestBuilders, provide custom BLoC instances, and listen to state changes. |
> | Key classes | `CometChatMessageList` · `CometChatConversations` |
> | Related | [Message List](https://www.cometchat.com/docs/ui-kit/flutter/message-list.md) · [Conversations](https://www.cometchat.com/docs/ui-kit/flutter/conversations.md) |

Each component's BLoC manages data fetching, state transitions, and business logic. You can configure it via RequestBuilders, provide a custom BLoC instance, or extend the default one.

## Configuring Data Fetching with RequestBuilders

Use request builders to control what data the component fetches. Pass the builder instance — not the result of `.build()`.

> [tab] Dart
>
> ```dart theme={null}
> CometChatMessageList(
>   user: user,
>   messagesRequestBuilder: MessagesRequestBuilder()
>     ..uid = user.uid
>     ..searchKeyword = 'hello'
>     ..limit = 30,
> )
> ```

> [!WARNING]
>
> The following parameters in `MessagesRequestBuilder` will always be altered inside the message list: UID, GUID, types, categories.

### Request Builder by Component

| Component | Builder Property | Builder Type |
| - | - | - |
| `CometChatConversations` | `conversationsRequestBuilder` | `ConversationsRequestBuilder` |
| `CometChatUsers` | `usersRequestBuilder` | `UsersRequestBuilder` |
| `CometChatGroups` | `groupsRequestBuilder` | `GroupsRequestBuilder` |
| `CometChatGroupMembers` | `groupMembersRequestBuilder` | `GroupMembersRequestBuilder` |
| `CometChatMessageList` | `messagesRequestBuilder` | `MessagesRequestBuilder` |

## Providing a Custom BLoC

Each component accepts an optional BLoC parameter. Provide your own instance to override default behavior:

> [tab] Dart
>
> ```dart theme={null}
> final myBloc = MessageListBloc(
>   user: user,
>   parentMessageId: null,
>   types: MessageTemplateUtils.getAllMessageTypes(),
>   categories: MessageTemplateUtils.getAllMessageCategories(),
> );
>
> CometChatMessageList(
>   user: user,
>   messageListBloc: myBloc,
> )
> ```

### BLoC Parameters by Component

| Component | BLoC Property | BLoC Type |
| - | - | - |
| `CometChatConversations` | `conversationsBloc` | `ConversationsBloc` |
| `CometChatMessageList` | `messageListBloc` | `MessageListBloc` |
| `CometChatMessageComposer` | `messageComposerBloc` | `MessageComposerBloc` |

## Extending the Default BLoC

Extend the default BLoC class and override hooks to add custom behavior:

> [tab] Dart
>
> ```dart theme={null}
> class CustomMessageListBloc extends MessageListBloc {
>   CustomMessageListBloc({required User user})
>       : super(user: user);
>
>   @override
>   void onItemAdded(BaseMessage item, List<BaseMessage> updatedList) {
>     // Custom logic when a message is added
>     debugPrint('Message added: ${item.id}');
>     super.onItemAdded(item, updatedList);
>   }
>
>   @override
>   void onItemRemoved(BaseMessage item, List<BaseMessage> updatedList) {
>     // Custom logic when a message is removed
>     super.onItemRemoved(item, updatedList);
>   }
>
>   @override
>   void onItemUpdated(BaseMessage oldItem, BaseMessage newItem, List<BaseMessage> updatedList) {
>     // Custom logic when a message is updated
>     super.onItemUpdated(oldItem, newItem, updatedList);
>   }
> }
> ```

### ListBase Hooks

All list-based BLoCs use the `ListBase` mixin with these override hooks:

| Hook | Called When |
| - | - |
| `onItemAdded(item, updatedList)` | An item is added to the list |
| `onItemRemoved(item, updatedList)` | An item is removed from the list |
| `onItemUpdated(oldItem, newItem, updatedList)` | An item is updated in the list |
| `onListCleared(previousList)` | The list is cleared |
| `onListReplaced(previousList, newList)` | The entire list is replaced |

## Component-Specific BLoC Events

Each component's BLoC has its own events and methods. See the individual component docs for details:

* [Message List — BLoC Events & Methods](https://www.cometchat.com/docs/ui-kit/flutter/message-list.md#advanced)
* [Conversations — BLoC Events](https://www.cometchat.com/docs/ui-kit/flutter/conversations.md#advanced)
* [Users — BLoC Events](https://www.cometchat.com/docs/ui-kit/flutter/users.md#advanced)
* [Groups — BLoC Events](https://www.cometchat.com/docs/ui-kit/flutter/groups.md#advanced)
* [Group Members — BLoC Events](https://www.cometchat.com/docs/ui-kit/flutter/group-members.md#advanced)

## Lifecycle Callbacks

> [tab] Dart
>
> ```dart theme={null}
> CometChatMessageList(
>   user: user,
>   onLoad: (messages) {
>     debugPrint('Loaded ${messages.length} messages');
>   },
>   onEmpty: () {
>     debugPrint('No messages found');
>   },
>   onError: (e) {
>     debugPrint('Error: $e');
>   },
> )
> ```

## Related

* [Message List](https://www.cometchat.com/docs/ui-kit/flutter/message-list.md) — Full message list component reference.
* [Customization Overview](https://www.cometchat.com/docs/ui-kit/flutter/customization-overview.md) — See all customization categories.

***

## Repository & Datasource Overrides

Both `CometChatConversations` and `CometChatMessageList` follow the same clean architecture stack. There are two override points:

```
Widget → BLoC → UseCase → Repository → DataSource (Remote + Local)
                  ↑               ↑
          override here    or here
```

### 1. Datasource Override

Implement the abstract datasource interfaces to swap the data layer entirely — e.g. a REST API instead of the CometChat SDK, or a persistent cache instead of in-memory.

#### Conversations

> [tab] Dart
>
> ```dart theme={null}
> abstract class ConversationsRemoteDataSource {
>   Future<List<Conversation>> getConversations({int limit, String? fromId});
>   Future<Conversation> getConversation(String conversationId);
>   Future<void> deleteConversation(String conversationWith, String conversationType);
>   Future<void> markMessageAsRead(BaseMessage message);
>   Future<Conversation> updateConversation(Conversation conversation);
> }
>
> abstract class ConversationsLocalDataSource {
>   Future<void> cacheConversations(List<Conversation> conversations);
>   Future<List<Conversation>> getCachedConversations();
>   Future<void> cacheConversation(Conversation conversation);
>   Future<Conversation?> getCachedConversation(String conversationId);
>   Future<void> removeCachedConversation(String conversationId);
>   Future<void> clearCache();
>   Future<bool> hasCachedData();
> }
> ```

#### Message List

> [tab] Dart
>
> ```dart theme={null}
> abstract class MessageListRemoteDataSource {
>   Future<GetMessagesResult> getMessages({...});
>   Future<List<BaseMessage>> fetchPreviousMessages({required MessagesRequest request});
>   Future<List<BaseMessage>> fetchNextMessages({required MessagesRequest request});
>   Future<void> markAsRead(BaseMessage message);
>   Future<void> markAsDelivered(BaseMessage message);
>   Future<User?> getLoggedInUser();
>   Future<Conversation> getConversation({...});
>   Future<Conversation> markMessageAsUnread(BaseMessage message);
> }
>
> abstract class MessageListLocalDataSource {
>   Future<void> cacheMessages(String conversationId, List<BaseMessage> messages);
>   Future<List<BaseMessage>> getCachedMessages(String conversationId);
>   // ... cache CRUD methods
> }
> ```

***

### 2. Repository Override

The repository interfaces sit above the datasources. Override here to change business logic — caching strategy, error handling, retry logic — without touching the datasource layer.

#### Conversations

> [tab] Dart
>
> ```dart theme={null}
> abstract class ConversationsRepository {
>   Future<Result<List<Conversation>>> getConversations({int limit, String? fromId});
>   Future<Result<Conversation>> getConversationById(String conversationId);
>   Future<Result<void>> deleteConversation(String conversationId);
>   Future<Result<Conversation>> updateConversation(Conversation conversation);
>   Future<Result<User?>> getLoggedInUser();
>   Future<Result<void>> markAsDelivered(BaseMessage message);
>   Future<Result<Conversation>> getConversation({...});
> }
> ```

#### Message List

> [tab] Dart
>
> ```dart theme={null}
> abstract class MessageListRepository {
>   Future<Result<List<BaseMessage>>> getMessages({...});
>   Future<Result<List<BaseMessage>>> fetchPreviousMessages({...});
>   Future<Result<List<BaseMessage>>> fetchNextMessages({...});
>   Future<Result<void>> markAsRead(BaseMessage message);
>   Future<Result<void>> markAsDelivered(BaseMessage message);
>   Future<Result<User?>> getLoggedInUser();
>   Future<Result<Conversation>> getConversation({...});
>   Future<Result<Conversation>> markMessageAsUnread(BaseMessage message);
> }
> ```

***

### 3. Wiring via the Service Locator

The service locators are the injection point. Both are singletons with a `setup()` method. Call `reset()` first, then `setup()` with your custom implementations before the widget mounts.

#### Datasource-level override (Conversations)

> [tab] Dart
>
> ```dart theme={null}
> class MyConversationsRemoteDataSource implements ConversationsRemoteDataSource {
>   @override
>   Future<List<Conversation>> getConversations({int limit = 30, String? fromId}) async {
>     // Your REST API call, mock data, etc.
>   }
>   // ... implement remaining methods
> }
>
> // Before mounting CometChatConversations:
> await ConversationsServiceLocator.instance.reset();
>
> final remote = MyConversationsRemoteDataSource();
> final local = ConversationsLocalDataSourceImpl(); // keep default cache
> final repo = ConversationsRepositoryImpl(
>   remoteDataSource: remote,
>   localDataSource: local,
> );
> ```

#### Repository-level override (Message List)

> [tab] Dart
>
> ```dart theme={null}
> class MyMessageListRepository implements MessageListRepository {
>   @override
>   Future<Result<List<BaseMessage>>> getMessages({...}) async {
>     // Custom logic
>   }
>   // ...
> }
>
> // Before mounting CometChatMessageList:
> await MessageListServiceLocator.instance.reset();
> // Wire your repo into use cases and pass to the BLoC
> ```

***

### Key Points

| Point | Detail |
| - | - |
| `reset()` | Sets `_isInitialized = false` — always call before re-wiring |
| `setup()` | Guarded by `_isInitialized` — safe to call multiple times normally |
| `localDataSource` in `MessageListRepositoryImpl` | Optional — pass `null` to disable caching entirely |
| Fallback caching | `ConversationsRepositoryImpl` falls back to local cache when remote fails — your custom remote inherits this if you use `ConversationsRepositoryImpl` with a custom datasource |
| `Result<T>` | All repository methods return `Result<T>` (`Success`/`Failure`) — your implementations must do the same |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.