🔮 AlchemyUI Chat
A lightweight and enchanted chat UI library for web applications. Transform your chat interface with magical theming, smooth animations, and powerful features.
✨ Installation
npm i @alchemyui/chat
Via NPM
Install AlchemyUI using npm:
npm i @alchemyui/chat
Via CDN
You can also include AlchemyUI directly in your HTML using unpkg:
<script src="https://unpkg.com/@alchemyui/chat/dist/alchemy.js"></script>
When using the CDN version, AlchemyUI will be available globally as AlchemyChat:
const chat = new AlchemyChat('#chat-container', {
// your configuration here
});ChatGPT Integration
For ChatGPT integration, install our experimental package:
npm i @alchemyui/chatgpt
⚠️ Note: The ChatGPT integration package is experimental and may have breaking changes in future releases.
🧪 Usage Examples
WebSocket Chat
import { AlchemyChat } from '@alchemyui/chat';
const chat = new AlchemyChat('#chat-container', {
messaging: {
backend: {
type: 'websocket',
endpoint: 'wss://your-server.com/chat',
protocols: [], // Optional WebSocket protocols
reconnect: true
},
transform: {
// Transform incoming messages before display
incoming: (data) => {
if (typeof data === 'string') return data;
return data.message || data.text;
},
// Transform outgoing messages before sending
outgoing: (message) => {
return { text: message, timestamp: new Date() };
}
}
},
callbacks: {
onReady: (chat) => {
console.log('Chat is ready!');
},
onConnect: () => {
chat.addMessage({
text: 'Connected to chat server',
type: 'system'
});
},
onDisconnect: () => {
chat.addMessage({
text: 'Connection lost. Reconnecting...',
type: 'system'
});
},
onError: (error) => {
console.error('WebSocket error:', error);
}
}
});REST API Integration
import { AlchemyChat } from '@alchemyui/chat';
const chat = new AlchemyChat('#chat-container', {
messaging: {
backend: {
type: 'rest',
endpoint: '/api/chat'
},
transform: {
// Transform API responses
incoming: (response) => response.reply || response.message,
// Transform outgoing messages
outgoing: (message) => ({ message, timestamp: new Date() })
}
},
callbacks: {
onSend: async (message) => {
try {
const response = await fetch('/api/chat', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(chat.config.messaging.transform.outgoing(message))
});
const data = await response.json();
chat.addMessage({
text: chat.config.messaging.transform.incoming(data),
type: 'incoming'
});
} catch (error) {
chat.addMessage({
text: 'Failed to send message',
type: 'error'
});
}
}
}
});Basic Usage
// Import AlchemyUI Chat
import { AlchemyChat } from '@alchemyui/chat';
// Initialize with basic configuration
const chat = new AlchemyChat('#chat-container', {
theme: {
mode: 'dark',
colors: {
primary: '#a855f7',
background: '#0f172a',
surface: '#1e293b',
textPrimary: '#e2e8f0',
textSecondary: '#94a3b8'
}
},
callbacks: {
onSend: (message) => {
// Echo the message back after a delay
setTimeout(() => {
chat.addMessage({
text: `You said: ${message}`,
type: 'incoming'
});
}, 1000);
}
}
});
// Add a welcome message
chat.addMessage({
text: '✨ Welcome to AlchemyUI Chat!',
type: 'incoming'
});HTML Setup
<!DOCTYPE html>
<html>
<head>
<title>AlchemyUI Chat</title>
<style>
#chat-container {
height: 500px;
max-width: 800px;
margin: 2rem auto;
}
</style>
</head>
<body>
<div id="chat-container"></div>
<script src="node_modules/@alchemyui/chat/dist/alchemy.js"></script>
<script src="chat.js"></script>
</body>
</html>🎨 Configuration
The chat can be extensively customized through its configuration object:
{
// Theme configuration
theme: {
mode: 'light', // or 'dark'
light: {
colors: {
primary: '#007bff',
background: '#ffffff',
textPrimary: '#212529',
textSecondary: '#6c757d',
incomingMessage: '#f8f9fa',
outgoingMessage: '#007bff',
inputBackground: '#ffffff',
borderColor: '#dee2e6'
}
},
dark: {
colors: {
// Dark theme colors...
}
},
sizing: {
borderRadius: '8px',
messageBorderRadius: '1rem',
inputHeight: '2.5rem',
fontSize: '0.95rem'
}
},
// Interface settings
interface: {
showTimestamp: true,
showAvatars: true,
showTypingIndicator: true,
messageAlignment: 'sides', // or 'left'/'right'
inputPlaceholder: 'Type a message...',
preferSystemTheme: true
},
// Message handling
messaging: {
backend: {
type: 'websocket', // or 'rest'
endpoint: 'wss://your-server.com/chat',
reconnect: true
},
transform: {
incoming: (data) => data,
outgoing: (data) => data
}
},
// Local storage
storage: {
enable: true,
type: 'local',
key: 'alchemyjs_messages'
},
// Event callbacks
callbacks: {
onReady: (chat) => {},
onSend: (message) => {},
onReceive: (message) => {},
onConnect: () => {},
onDisconnect: () => {},
onError: (error) => {}
}
}🌟 Features
- 🎭 Dark/Light mode with system theme support
- 📱 Responsive design
- 💾 Optional message persistence
- ⚡ Real-time message handling
- 🎨 Customizable themes
- 🔧 Configurable interface
- 🪄 Message transformations
- 🔄 Automatic reconnection for WebSocket
- 🎯 TypeScript support
🔮 API Reference
Methods
addMessage(message)
Add a new message to the chat.
chat.addMessage({
text: 'Hello!',
type: 'incoming', // or 'outgoing', 'system', 'error'
timestamp: new Date(),
avatar: 'path/to/avatar.png' // optional
});setTheme(mode)
Switch between light and dark themes.
chat.setTheme('dark'); // or 'light'clearMessages()
Clear all messages from the chat.
chat.clearMessages();loadMessages()
Load messages from storage (if enabled).
const loaded = chat.loadMessages();setTyping(status)
Show/hide typing indicator.
chat.setTyping(true); // Show typing
chat.setTyping(false); // Hide typingupdateConfig(config)
Update chat configuration.
chat.updateConfig({
theme: {
colors: {
primary: '#a855f7'
}
}
});Events
onSend
Called when a message is sent.
const chat = new AlchemyChat('#chat', {
callbacks: {
onSend: (message) => {
console.log('Message sent:', message);
}
}
});onReceive
Called when a message is received.
const chat = new AlchemyChat('#chat', {
callbacks: {
onReceive: (message) => {
console.log('Message received:', message);
}
}
});onType
Called when the user is typing.
const chat = new AlchemyChat('#chat', {
callbacks: {
onType: (text) => {
socket.emit('typing', { text });
}
}
});onError
Called when an error occurs.
const chat = new AlchemyChat('#chat', {
callbacks: {
onError: (error) => {
console.error('Chat error:', error);
}
}
});Configuration
Full Configuration Object
{
theme: {
mode: 'dark',
colors: {
primary: '#a855f7',
background: '#0f172a',
surface: '#1e293b',
textPrimary: '#e2e8f0',
textSecondary: '#94a3b8',
border: 'rgba(148, 163, 184, 0.1)',
incomingMessage: '#1e1b4b',
outgoingMessage: '#a855f7',
timestamp: '#64748b',
inputBackground: '#0f172a',
inputText: '#e2e8f0',
inputPlaceholder: '#64748b',
buttonBackground: '#a855f7',
buttonText: '#ffffff',
systemMessage: '#1e293b'
},
sizing: {
borderRadius: '12px',
messageBorderRadius: '1rem',
inputHeight: '3rem',
fontSize: '0.95rem',
spacing: '1rem',
maxWidth: '800px'
},
fonts: {
primary: 'Inter, system-ui, sans-serif',
code: 'Fira Code, monospace'
},
effects: {
messageShadow: '0 2px 4px rgba(0, 0, 0, 0.05)',
inputShadow: '0 2px 4px rgba(0, 0, 0, 0.05)',
transition: 'all 0.2s ease'
}
},
interface: {
showTimestamp: true,
showAvatars: true,
showTypingIndicator: true,
messageAlignment: 'sides',
inputPlaceholder: 'Type a message...',
sendButtonIcon: '➤'
},
storage: {
enable: true,
type: 'local',
key: 'alchemyui_messages'
},
messages: {
welcome: '👋 Welcome to AlchemyUI Chat!',
error: '⚠️ Failed to send message',
reconnecting: '🔄 Reconnecting...',
connected: '✨ Connected to chat'
}
}