UseChat SDK - React Native Chat UI Library

A professional, customizable chat component library for React Native with a modern architecture that separates UI from logic.

Note: UseChat SDK is licensed under a custom license. See LICENSING.md for details. Free for personal/educational use, commercial license required for business applications.

Features

• Render Props Architecture: Customize any part of the UI using render props
• Standalone Hooks: Use chat logic without UI components
• Pluggable Attachment System: Easy integration with your backend
• TypeScript First: Full type safety and IntelliSense support
• Customizable Components: Override any component with your own implementation

Architecture Overview

The library follows a clean separation of concerns:

• Components: UI components that can be customized via render props
• Hooks: Logic-only hooks that can be used independently
• Types: Shared TypeScript interfaces
• Plugins: Optional attachment plugins for different file types

Quick Start

Basic Usage

import { Chat } from '@your-org/chat';

const MyChat = () => (
  <Chat
    chatName="My Chat"
    onMessageSend={(message) => console.log('Message sent:', message)}
    onBack={() => navigation.goBack()}
  />
);

Using Render Props

<Chat
  chatName="Custom Chat"
  renderProps={{
    renderMessage: (props) => <CustomMessage {...props} />,
    renderInput: (props) => <CustomInput {...props} />,
    renderHeader: (props) => <CustomHeader {...props} />,
  }}
  onMessageSend={handleMessageSend}
/>

Using Standalone Hooks

Components

Chat

The main chat component that orchestrates all functionality.

Props:

• chatName: Name displayed in the header
• messages: Array of messages to display
• renderProps: Object containing render functions for customization
• components: Object containing component overrides
• attachmentUploader: Function to handle file uploads
• maxAttachments: Maximum number of attachments per message
• maxFileSize: Maximum file size in bytes
• allowedFileTypes: Array of allowed MIME types

Render Props:

• renderMessage: Custom message rendering
• renderInput: Custom input component
• renderHeader: Custom header component
• renderActionSheet: Custom action sheet
• renderReactionDetails: Custom reaction details

MessageList

Displays a list of messages with scrolling and typing indicators.

MessageInput

Handles text input, attachments, and message sending.

ChatScreenHeader

Displays chat information and action buttons.

MessageActionSheet

Shows message actions (reply, copy, delete, reactions).

ReactionDetailsSheet

Displays detailed reaction information.

Hooks

useAttachments

Manages attachment lifecycle and uploads.

const {
  attachments,
  openPicker,
  addAttachment,
  removeAttachment,
  uploadAttachments,
  isUploading,
} = useAttachments({
  uploader: myUploader,
  maxAttachments: 10,
  maxFileSize: 10 * 1024 * 1024,
});

useTypingIndicator

Manages typing indicator state.

const {
  isTyping,
  startTyping,
  stopTyping,
  typingUsers,
} = useTypingIndicator({
  typingTimeout: 3000,
});

useMessageList

Manages message list scrolling and interactions.

const {
  messageListRef,
  showScrollToBottomButton,
  scrollToBottom,
  handleScroll,
} = useMessageList({
  messages,
  onMessageLongPress,
  onReactionPress,
});

useMessageInput

Manages message input state and validation.

const {
  message,
  composerHeight,
  handleTextChange,
  handleSend,
  handleFocus,
} = useMessageInput({
  onSend: handleMessageSend,
  maxLength: 1000,
});

Attachment System

The library provides a pluggable attachment system that supports:

• Image Picker: Select images from gallery or camera
• Document Picker: Select documents and files
• Location Sharing: Share current location
• Contact Sharing: Share contact information

Custom Uploader

const myUploader: AttachmentUploader = {
  upload: async (file) => {
    const formData = new FormData();
    formData.append('file', file);
    
    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData,
    });
    
    const result = await response.json();
    return {
      url: result.url,
      metadata: result.metadata,
    };
  },
  
  validate: (file) => {
    if (file.size > 10 * 1024 * 1024) {
      return 'File too large';
    }
    return true;
  },
};

Customization Examples

Custom Message Component

const CustomMessage = ({ message, onLongPress, onReactionPress }) => (
  <View style={styles.message}>
    <Text style={styles.text}>{message.text}</Text>
    <Text style={styles.time}>
      {new Date(message.timestamp).toLocaleTimeString()}
    </Text>
    {message.reactions?.map((reaction, index) => (
      <TouchableOpacity
        key={index}
        onPress={() => onReactionPress(message)}
      >
        <Text>{reaction.emoji} {reaction.count}</Text>
      </TouchableOpacity>
    ))}
  </View>
);

Custom Input Component

const CustomInput = ({ 
  value, 
  onChangeText, 
  onSend, 
  attachments,
  onAttachmentAdd,
  onAttachmentRemove 
}) => (
  <View style={styles.inputContainer}>
    <TextInput
      value={value}
      onChangeText={onChangeText}
      placeholder="Type a message..."
      style={styles.textInput}
    />
    <TouchableOpacity onPress={onSend} style={styles.sendButton}>
      <Text>Send</Text>
    </TouchableOpacity>
    
    {attachments.map(attachment => (
      <View key={attachment.id} style={styles.attachment}>
        <Text>{attachment.fileName}</Text>
        <TouchableOpacity onPress={() => onAttachmentRemove(attachment.id)}>
          <Text>×</Text>
        </TouchableOpacity>
      </View>
    ))}
  </View>
);

TypeScript Support

All components and hooks are fully typed with TypeScript. The library exports comprehensive type definitions for:

• Message and attachment interfaces
• Hook return types
• Component prop types
• Render prop interfaces

Migration from v1

If you're upgrading from the previous version:

1. Replace onMessageSend: The callback now receives a Message object instead of separate parameters
2. Update attachment handling: Use the new useAttachments hook or attachmentUploader prop
3. Component overrides: Use renderProps instead of components for UI customization
4. Hooks: Extract logic into standalone hooks for better reusability

📄 License

UseChat SDK is licensed under a Custom License Agreement:

• ✅ Free for personal, educational, and small-scale use
• 💼 Commercial license required for business applications
• 📋 Full details: See LICENSING.md

Quick Licensing Guide

| Use Case | License Required | Attribution | |----------|------------------|-------------| | Personal projects | Free | Required | | Educational use | Free | Required | | Open source projects | Free | Required | | Apps with <1,000 MAU | Free | Required | | Commercial/Business apps | Commercial | Optional | | Apps with 1,000+ MAU | Commercial | Optional |

Contact: [email protected] for commercial licensing

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📞 Support

• Documentation: https://docs.usechat.dev
• Issues: GitHub Issues
• Email: [email protected]
• Website: https://usechat.dev