Chat

The Chat component provides a flexible and interactive messaging interface for applications. It supports both incoming and outgoing messages with avatars, sender names, timestamps, and a message input area with a send button.

Dependencies

• Textarea component (imported from ”../textarea/index.js”)
• Button component (imported from ”../button/index.js”)

Usage

See the Example by Serhii Pimenov on CodePen.

Basic Usage

<div data-role="chat"></div>

With Configuration Options

<div data-role="chat"
     data-name="John Smith"
     data-avatar="<span>👨</span>"
     data-welcome="Welcome to our chat! How can I help you today?"
     data-welcome-avatar="<span>🤖</span>"
     data-title="Customer Support"
     data-width="100%"
     data-height="400px">
</div>

Programmatic Initialization

const chat = Metro.makePlugin("#myChatElement", "chat", {
    name: "John Smith",
    avatar: "<span>👨</span>",
    welcome: "Welcome to our chat! How can I help you today?",
    welcomeAvatar: "<span>🤖</span>",
    title: "Customer Support",
    width: "100%",
    height: "400px"
});

Plugin Parameters

Parameter	Type	Default	Description
chatDeferred	number	0	Deferred initialization time in milliseconds
inputTimeFormat	string	null	Format for parsing input time strings
timeFormat	string	”D MMM hh:mm A”	Format for displaying message timestamps
name	string	”John Doe”	Default name for outgoing messages
avatar	string	”👦“	HTML for the avatar of outgoing messages
welcome	string	null	Welcome message text (displayed when chat initializes)
welcomeAvatar	string	”👽“	HTML for the avatar of the welcome message
title	string	null	Title for the chat component
width	string	”100%“	Width of the chat component
height	string	”auto”	Height of the chat component
initialHeight	number	100	Initial Height of the chat component
messages	object	null	Initial messages to display
attachAccept	string	”*“	Attach file types
readonly	boolean	false	Whether the chat is in read-only mode
sendMode	string	”enter”	Trigger for message send: enter, control+enter, button
useEmoji	boolean	true	Use emoji in message
useLink	boolean	true	Use link in message
useCode	boolean	true	Use code blocks in message
buttons	string	”send attach”	Buttons to use
clsChat	string	""	Additional CSS class for the chat container
clsName	string	""	Additional CSS class for the sender name
clsTime	string	""	Additional CSS class for the message time
clsInput	string	""	Additional CSS class for the input field
clsSendButton	string	""	Additional CSS class for the send button
clsMessageLeft	string	”default”	CSS class for left-aligned messages
clsMessageRight	string	”default”	CSS class for right-aligned messages

Message Structure

Each message object should contain the following properties:

• text - Message text
• time - Message timestamp
• position - “left” or “right”
• name - Sender name
• avatar - Sender avatar HTML
• id (optional) - Unique message ID
• attach (optional) - Attachment, must be a file object

API Methods

To access the Chat API methods, use:

const chat = Metro.getPlugin("#myChatElement", "chat");

• add(msg) - Adds a message to the chat. The message object should contain:

chat.add({
    id: "msg-1", // Optional unique ID for the message
    name: "User Name",
    avatar: "<span>👨</span>", // Can be HTML, image URL, or data URL
    text: "Hello, world!",
    position: "left", // "left" or "right"
    time: new Date() // Date object or string
});

const attach = new File(["content"], "file.txt", { type: "text/plain" });
chat.add({
    name: "User Name",
    avatar: "<span>👨</span>",
    position: "right",
    time: new Date(),
    attach: attach // File object for attachment
});

• addMessages(messages) - Adds multiple messages to the chat.

chat.addMessages([
    {
        name: "User 1",
        avatar: "<span>👨</span>",
        text: "Hello!",
        position: "left",
        time: new Date()
    },
    {
        name: "User 2",
        avatar: "<span>👩</span>",
        text: "Hi there!",
        position: "right",
        time: new Date()
    }
]);

• delMessage(id) - Deletes a message by ID.

• updMessage(msg) - Updates a message. The message object should contain:

• id - Message ID to update
• text - New message text
• time - New message timestamp

• clear() - Clears all messages from the chat.

• toggleReadonly(readonly) - Toggles the read-only state of the chat.

Events

Event	Description
onMessage	Triggered when a message is added to the chat
onSend	Triggered when a message is sent
onSendButtonClick	Triggered when the send button is clicked
onChatCreate	Triggered when the chat component is created

Styling with CSS Variables

Variable	Default (Light)	Dark Mode	Description
--chat-border-color	var(—border-color)	var(—border-color)	Border color for the chat component
--chat-background	#ffffff	#343637	Background color for the chat component
--chat-color	#191919	#dbdfe7	Text color for the chat component
--chat-message-background	#f5f5f5	#4a4d51	Background color for chat messages
--chat-message-color	#191919	#dbdfe7	Text color for chat messages

Example of Custom Styling

/* Custom styling for chat */
.custom-chat {
    --chat-border-color: #2196F3;
    --chat-background: #E3F2FD;
    --chat-color: #0D47A1;
    --chat-message-background: #BBDEFB;
    --chat-message-color: #0D47A1;
}

Available CSS Classes

Base Classes

• .chat - Main container class
• .title - Chat title
• .messages - Messages container
• .message-input - Input area container
• .chat-input - Text input field

Message Classes

• .message - Message container
• .message.left - Left-aligned message (incoming)
• .message.right - Right-aligned message (outgoing)
• .message-item - Message item container
• .message-avatar - Message avatar
• .message-text - Message text container
• .message-text-inner - Message text content
• .message-sender - Message sender name
• .message-time - Message timestamp
• .--next - Modifier for consecutive messages from the same side

Best Practices

1. Use appropriate avatars to distinguish between different users
2. Keep message texts concise for better readability
3. Use the welcome message to provide initial instructions or greeting
4. Consider using custom styling to match your application’s theme
5. Use the readonly mode for displaying chat history without allowing new messages