v_chat_sdk

The public umbrella package for the V Chat Flutter SDK. Its primary library exports the Flutter SDK integration and the optional accessible, localized, themeable widget library from one dependency.

Release candidate 2.0.0-rc.4 supports Flutter >=3.38.0 and Dart >=3.10.0-0 <4.0.0. It is a breaking successor to the legacy v_chat_sdk 1.x package. Read MIGRATION.md before upgrading. The widget implementation remains presentation-only: it owns no client session, network request, database, authorization decision, retry, navigation, or state-management framework.

Installation

flutter pub add v_chat_sdk

Import the complete SDK and UI surface from the primary library:

import 'package:v_chat_sdk/v_chat_sdk.dart';

Client applications use only short-lived app-user tokens obtained from their own authenticated backend. Never embed a V Chat application credential, dashboard session secret, or signing key in a Flutter build. Compose one VChatFlutterSdk per signed-in user, call connectUser, and await dispose() during logout or profile switching. The complete lifecycle, REST, realtime, persistence, push, cancellation, and error examples are documented by v_chat_flutter.

Add localization and theme

import 'package:flutter/material.dart';
import 'package:flutter_localizations/flutter_localizations.dart';
import 'package:v_chat_sdk/v_chat_sdk.dart';

final colorScheme = ColorScheme.fromSeed(seedColor: Colors.indigo);

MaterialApp(
  supportedLocales: VChatUiLocalizations.supportedLocales,
  localizationsDelegates: const <LocalizationsDelegate<dynamic>>[
    VChatUiLocalizations.delegate,
    GlobalMaterialLocalizations.delegate,
    GlobalWidgetsLocalizations.delegate,
    GlobalCupertinoLocalizations.delegate,
  ],
  theme: ThemeData(
    colorScheme: colorScheme,
    extensions: <ThemeExtension<dynamic>>[
      VChatUiThemeData.fromColorScheme(colorScheme),
    ],
  ),
  home: const ChatScreen(),
);

English and Arabic are included. Flutter's localization delegates supply text direction and the Material/Cupertino strings needed for correct RTL behavior. VChatUiThemeData.fromColorScheme provides complete defaults; use copyWith when your design system needs selected colors, spacing, bubble radius, breakpoint, or pane width overrides.

Map SDK state into UI models

The widgets accept deliberately small, immutable presentation models. The host chooses safe display labels and timestamp formatting:

final rows = conversationSnapshots.map(
  (snapshot) => VChatUiConversation.fromSnapshot(
    snapshot,
    title: resolveConversationTitle(snapshot),
    preview: resolveConversationPreview(snapshot),
    timestampLabel: formatConversationTime(snapshot),
  ),
).toList(growable: false);

final messages = messageSnapshots.map(
  (snapshot) => VChatUiMessage.fromSnapshot(
    snapshot,
    currentUserId: currentUserId,
    authorLabel: resolveAuthorLabel(snapshot),
    timestampLabel: formatMessageTime(snapshot),
  ),
).toList(growable: false);

fromSnapshot copies only released display state and does not retain custom payloads. Use the direct constructors when presenting a host-owned optimistic row; select pending, failed, or sent delivery status explicitly and reconcile it with the server result.

Build a responsive chat screen

VChatAdaptiveChatLayout(
  showDetailOnCompact: selectedConversationId != null,
  conversationsPane: VChatConversationListView(
    items: rows,
    selectedConversationId: selectedConversationId,
    isLoadingMore: isLoadingMoreConversations,
    onLoadMore: loadMoreConversations,
    onConversationPressed: selectConversation,
  ),
  detailPane: Column(
    children: <Widget>[
      VChatConnectionStatusBanner(
        status: connectionStatus,
        actionLabel: canRetry ? 'Retry' : null,
        onAction: canRetry ? retryRealtime : null,
      ),
      Expanded(
        child: VChatMessageListView(
          messages: messages,
          isLoadingOlder: isLoadingOlderMessages,
          onLoadOlder: loadOlderMessages,
          onReact: reactToMessage,
          onOpenReplies: openReplies,
          onRetry: retryFailedMessage,
        ),
      ),
      VChatTypingIndicator(
        userLabels: visibleTypingUserLabels,
        totalCount: typingUserCount,
        truncated: typingUserCount > visibleTypingUserLabels.length,
      ),
      VChatMessageComposer(
        controller: composerController,
        enabled: canSend,
        isSending: isSending,
        clearOnSend: false,
        onSend: sendMessage,
      ),
    ],
  ),
);

Pass messages oldest-to-newest; the list keeps the newest row at the bottom. Pagination is always explicit through onLoadMore and onLoadOlder—scrolling does not silently perform network work. The host owns compact navigation by changing showDetailOnCompact.

Keep clearOnSend: false for asynchronous sends. Await the SDK mutation in host state, then clear the host-owned TextEditingController only after the message is accepted or intentionally converted to an optimistic row. This prevents text loss after a validation, authorization, or transport failure.

Widget reference

Widget/model Purpose Host responsibility
VChatAdaptiveChatLayout Compact or two-pane master/detail layout Selection and navigation
VChatConversationListView Lazy keyed conversation rows and load-more control Ordering, cursor, loading state
VChatConversationTile One conversation row Safe labels and selection callback
VChatMessageListView Lazy chronological message list Paging, mutations, optimistic state
VChatMessageBubble One accessible message/tombstone Retry, reaction, and reply actions
VChatMessageComposer Controlled, bounded text submission Async send and controller lifecycle
VChatTypingIndicator Ephemeral bounded typing label Map subscription activity to safe names
VChatConnectionStatusBanner Accessible connection/recovery state Map SDK state and choose explicit action
VChatEmptyState Reusable empty/error placeholder Optional action and product copy
VChatUiConversation Display-safe conversation projection Title, preview, timestamp, optimistic policy
VChatUiMessage Display-safe message projection Author label, timestamp, delivery status

Applications that only want presentation types may import the secondary library:

import 'package:v_chat_sdk/v_chat_flutter_ui.dart';

State ownership and safety

The host application owns:

  • VChatFlutterSdk, login/logout, app-user token retrieval, and exact user switching;
  • conversation/message streams, pagination cursors, loading/error state, and reconciliation;
  • channel selection, routing, dialogs, attachment pickers, and reply screens;
  • optimistic message IDs, retry decisions, moderation actions, and permission checks; and
  • push permissions, native notifications, analytics, and product-specific accessibility testing.

The widgets do not infer authorization from cached rows and do not sanitize unsafe product strings for you. Supply labels intended for display, avoid secrets/private URLs, and do not place arbitrary server error messages into semantics or visible UI.

Dispose every controller, focus node, and SDK stream subscription that your host creates. These widgets dispose only objects they allocate internally.

Accessibility and RTL

Lists use stable keys and semantic child counts. Message, unread, typing, retry, and connection states have localized semantic labels. Test large text scale, keyboard navigation, screen readers, contrast, narrow layouts, and both English and Arabic in the real application; package widget tests cannot validate the full host navigation or product copy.

Support and security

Read the repository support, security, and privacy policies before production adoption. This is a release candidate; pin the exact version and review the changelog before upgrading.

Libraries

v_chat_flutter_ui
Accessible, localized, themeable presentation components for V Chat.
v_chat_sdk
Public umbrella for the V Chat Flutter SDK and its optional UI components.