State Views

Replace the default empty, error, and loading state views with custom widgets.

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}');
  },
)

Related

• Customization Overview — See all customization categories.