State Views - CometChat Docs

Components display state views when the list is empty, an error occurs, or data is loading. You can replace these with custom widgets.

Replacing State Views

Each state view property accepts a WidgetBuilder — a function that takes BuildContext and returns a Widget.

Property	State
`emptyStateView`	No data to display
`errorStateView`	An error occurred during data fetching
`loadingStateView`	Data is being fetched
`emptyChatGreetingView`	Empty chat with a greeting (message list only)

Example: Custom Empty State

Dart

CometChatConversations(
  emptyStateView: (context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Icon(Icons.chat_bubble_outline, size: 64, color: Colors.grey),
          SizedBox(height: 16),
          Text(
            'No conversations yet',
            style: TextStyle(fontSize: 18, color: Colors.grey[700]),
          ),
          SizedBox(height: 8),
          Text(
            'Start a new chat to get going',
            style: TextStyle(fontSize: 14, color: Colors.grey),
          ),
        ],
      ),
    );
  },
)

Example: Custom Error State

Dart

CometChatMessageList(
  user: user,
  errorStateView: (context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Icon(Icons.error_outline, size: 48, color: Colors.red),
          SizedBox(height: 12),
          Text('Something went wrong'),
          SizedBox(height: 16),
          ElevatedButton(
            onPressed: () {
              // Trigger reload
            },
            child: Text('Try Again'),
          ),
        ],
      ),
    );
  },
)

Example: Custom Loading State

Dart

CometChatMessageList(
  user: user,
  loadingStateView: (context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          CircularProgressIndicator(color: Color(0xFF6851D6)),
          SizedBox(height: 16),
          Text('Loading messages...'),
        ],
      ),
    );
  },
)

Example: Empty Chat Greeting

The message list supports a special emptyChatGreetingView for new conversations:

Dart

CometChatMessageList(
  user: user,
  emptyChatGreetingView: (context) {
    return Center(
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          Icon(Icons.waving_hand, size: 48, color: Color(0xFF6851D6)),
          SizedBox(height: 16),
          Text('Say hello! 👋', style: TextStyle(fontSize: 18)),
        ],
      ),
    );
  },
)

Lifecycle Callbacks

Use lifecycle callbacks to run custom logic when states change:

Dart

CometChatMessageList(
  user: user,
  onLoad: (messages) {
    debugPrint('Loaded ${messages.length} messages');
  },
  onEmpty: () {
    debugPrint('No messages found');
  },
  onError: (e) {
    debugPrint('Error: ${e.message}');
  },
)

Customization Overview — See all customization categories.

​Replacing State Views

​Example: Custom Empty State

​Example: Custom Error State

​Example: Custom Loading State

​Example: Empty Chat Greeting

​Lifecycle Callbacks

​Related