Angular component library for embedding OpenWebUI chat with Socket.IO streaming, file attachments, and conversation history
npm install ngx-open-web-ui-chatbash
npm install ngx-open-web-ui-chat
`
β οΈ IMPORTANT: Required Setup
π Having issues? β TROUBLESHOOTING GUIDE
$3
`bash
npm install ngx-markdown marked socket.io-client
`
$3
THIS IS REQUIRED! Add these providers or the component won't work:
`typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideZonelessChangeDetection } from '@angular/core';
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
import { provideMarkdown } from 'ngx-markdown';
import { AppComponent } from './app/app.component';
bootstrapApplication(AppComponent, {
providers: [
provideZonelessChangeDetection(), // Required for zoneless mode
provideHttpClient(withInterceptorsFromDi()), // Required for HTTP
provideMarkdown() // Required for markdown rendering
]
}).catch((err) => console.error(err));
`
$3
`json
{
"polyfills": [] // Must be empty, no "zone.js"!
}
`
$3
`typescript
import { Component } from '@angular/core';
import { OpenwebuiChatComponent } from 'ngx-open-web-ui-chat';
@Component({
standalone: true,
imports: [OpenwebuiChatComponent],
template:
})
export class AppComponent {}
`
API
$3
| Input | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| endpoint | string | β
| - | OpenWebUI instance URL |
| modelId | string | β
| - | AI model identifier |
| apiKey | string | β
| - | API authentication key |
| enableMarkdown | boolean | β | true | Enable markdown rendering |
| debug | boolean | β | false | Enable debug logging |
| language | string | β | 'en' | UI language code |
| history | boolean | β | false | Enable chat history sidebar |
| folders | boolean | β | false | Enable folder support |
| notes | boolean | β | false | Enable notes feature |
| integrations | boolean | β | false | Enable integrations menu |
| tools | boolean | β | false | Enable tools selection menu |
| showReferenceChats | boolean | β | false | Enable reference chat selection |
| showReferenceNotes | boolean | β | false | Enable reference note selection |
| showAttachWebPage | boolean | β | false | Enable web page attachment feature |
| style | Partial | β | - | Custom CSS styles |
$3
| Output | Type | Description |
|--------|------|-------------|
| chatInitialized | EventEmitter | Emitted when chat session is ready |
| messagesChanged | EventEmitter | Emitted when message count changes |
$3
`typescript
// Send a message programmatically
sendMessage(message: string): void
// Clear all messages (keeps session)
clearChat(): void
// Create new chat session (clears messages)
createNewChat(): void
// Change to different model
changeModel(modelId: string): void
// Get available models (async)
async getModels(): Promise
`
Conversation History
The component automatically maintains full conversation context:
`json
[
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi! How can I help?"},
{"role": "user", "content": "What did I say before?"},
{"role": "assistant", "content": "You said 'Hello'"}
]
`
All previous messages are sent with each new request, enabling the AI to:
- Remember the entire conversation
- Provide context-aware responses
- Reference earlier messages
Examples
$3
`typescript
[endpoint]="'https://ai.example.com'"
[modelId]="'llama3'"
[apiKey]="'sk-abc123'">
`
$3
`typescript
import { Component, ViewChild } from '@angular/core';
import { OpenwebuiChatComponent } from 'ngx-open-web-ui-chat';
@Component({
standalone: true,
imports: [OpenwebuiChatComponent],
template:
})
export class AppComponent {
@ViewChild('chat') chat?: OpenwebuiChatComponent;
clearChat() {
this.chat?.clearChat();
}
sendHello() {
this.chat?.sendMessage('Hello!');
}
onReady() {
console.log('Chat ready!');
}
onMsgCount(count: number) {
console.log('Messages:', count);
}
}
`
$3
`typescript
[endpoint]="endpoint"
[modelId]="modelId"
[apiKey]="apiKey"
[language]="'en'">
`
Supported: en, zh, hi, es, ar, fr, pt, ru, bn, ja
$3
`typescript
[endpoint]="endpoint"
[modelId]="modelId"
[apiKey]="apiKey"
[enableMarkdown]="false">
`
Markdown Support
Enabled by default. Supports:
- Headers (H1-H6)
- Emphasis (bold, italic, strikethrough)
- Lists (ordered & unordered)
- Links and Images
- Code blocks (inline & multiline)
- Blockquotes
- Tables
- Horizontal rules
Example response:
``markdown
Title
Here's bold and code.
`javascript
console.log('Hello');
`
- Item 1
- Item 2
``
Will render as formatted HTML automatically!
Custom Styling
Override component styles:
`css
::ng-deep openwebui-chat {
.message.user {
background: #4CAF50;
}
.message.assistant {
background: #f0f0f0;
}
/ Markdown elements /
code {
background: #f5f5f5;
padding: 2px 4px;
}
}
`
Angular 2025 Architecture
$3
`typescript
provideZonelessChangeDetection()
`
No ZoneJS dependency = smaller bundle, better performance.
$3
`typescript
// Component state
messages = signal([]);
isLoading = signal(false);
`
Reactive, efficient, modern.
$3
`
src/lib/
βββ components/
β βββ openwebui-chat.ts β Main component logic
β βββ openwebui-chat.html β Main template
β βββ openwebui-chat.scss β Main styles
β βββ chat-input/ β Input component
β βββ chat-message/ β Message display component
β βββ chat-history-sidebar/ β History sidebar components
β β βββ sidebar/ β Main sidebar container
β β βββ list/ β Chat list
β β βββ item/ β Chat item
β β βββ header/ β Sidebar header
β β βββ context-menu/ β Chat context menu
β β βββ folder-list/ β Folder list
β β βββ folder-item/ β Folder item
β β βββ folder-context-menu/ β Folder context menu
β βββ archived-chats-modal/ β Archived chats modal component
β βββ attach-webpage-modal/ β Web page attachment modal component
β βββ chat-search-modal/ β Search modal
β βββ confirm-dialog/ β Confirmation dialogs
β βββ error-banner/ β Error display component
β βββ export-format-menu/ β Export options menu
β βββ note-editor/ β Note editor component
β βββ notes-sidebar/ β Notes sidebar component
β βββ message-actions/ β Action buttons component
β βββ rating-form/ β Rating form component
β βββ regenerate-menu/ β Regenerate menu component
β βββ text-selection-menu/ β Text selection context menu
β βββ ask-explain-modal/ β Ask/Explain modal component
βββ services/
β βββ openwebui-api.ts β API service
βββ models/
β βββ chat.model.ts β Type definitions
βββ utils/
β βββ audio-recorder.ts β Audio recording utility
β βββ date-formatter.ts β Date formatting utility
βββ i18n/
βββ translations.ts β Multi-language support
`
Clean separation of concerns with modular component architecture.
$3
`typescript
private service = inject(OpenWebUIService);
`
Modern dependency injection pattern.
Development
$3
`bash
npm run build
Output: dist/
`
$3
`bash
cd dist
npm link
In your app
npm link ngx-open-web-ui-chat
`
$3
See test-app/ for a complete example application.
Browser Support
- β
Chrome/Edge (latest)
- β
Firefox (latest)
- β
Safari (latest)
- β
Mobile browsers
Requirements
- Node.js: >= 20.19.0
- Angular: ^20.0.0
- TypeScript: ~5.8.0
Troubleshooting
$3
Problem: Markdown appears as plain text.
Solution: Add providers to main.ts:
`typescript
import { provideMarkdown } from 'ngx-markdown';
import { provideHttpClient, withInterceptorsFromDi } from '@angular/common/http';
bootstrapApplication(AppComponent, {
providers: [
provideHttpClient(withInterceptorsFromDi()),
provideMarkdown() // Required!
]
});
`
$3
Problem: Cannot find module 'ngx-open-web-ui-chat'
Solution:
1. npm install ngx-open-web-ui-chat
2. Restart TypeScript server
3. For local dev, use npm link
$3
Problem: AI doesn't remember previous messages.
Solution: This is fixed in v1.0.0+. Update to latest version:
`bash
npm update ngx-open-web-ui-chat
`
Documentation
Full documentation available in the repository:
- API Reference - Complete API docs
- Markdown Guide - Markdown features
- I18N Guide - Multi-language setup
Architecture
$3
The library uses Socket.IO for real-time bidirectional communication with OpenWebUI:
- WebSocket Connection - Persistent connection for instant message delivery
- Event-Driven - Handles chat:completion, status, and other events
- Automatic Reconnection - Resilient connection with retry logic
- Task Management - Tracks message generation via task IDs
- Completion Detection - Smart handling of finish signals
$3
1. Initial Connection - Socket.IO connects to /ws/socket.io on configure
2. Chat Creation - Creates new chat session via REST API
3. Message Sending - POST to /api/chat/completions with session_id and chat_id
4. Real-time Streaming - Server sends incremental content via Socket.IO events
5. Completion - Detects finish signals and saves conversation to server
Version History
$3
- β
Reference Notes Support - Reference notes in new messages
- β
Reference Note Menu - Browse and select notes to reference
- β
Visual Indicator - Referenced notes appear as badges
- β
Translations - Added reference note translation keys
$3
- β
Reference Chat Support - Reference previous conversations in new messages
- β
Reference Chat Menu - Browse and select chats to reference
- β
Visual Indicator - Referenced chats appear as badges
- β
Pagination - Load more chats with infinite scroll
- β
Translations - Added reference chat translation keys
$3
- β
Tools Support - Access and enable server-side tools from Open WebUI API
- β
Tools Menu - Select/deselect tools with visual checkmarks
- β
Tool Indicator - Visual badge showing enabled tools
- β
API Integration - Fetches tools from /api/v1/tools/ endpoint
- β
Translations - Added tools-related translation keys
$3
- β
Integrations Support - Toggle external capabilities
- β
Web Search - Enable/disable web search
- β
Code Interpreter - Enable/disable code execution
- β
Translations - Added support for integration keys
$3
- β
Archived Chats Modal - View, search, unarchive, and delete archived chats
- β
Search Archived - Debounced search through archived conversations
- β
Pagination - Load more archived chats with infinite scroll
- β
Accessibility - Focus trap and keyboard navigation for modal
$3
- β
Notes Support - Integrated markdown note editor
- β
Notes Sidebar - Create, edit, and organize notes
- β
Auto-save - Notes are automatically saved
$3
- β
Folder Support - Organize chats into folders with drag & drop
- β
Drag & Drop - Improved drag and drop experience for chats and folders
- β
Context Menus - Manage folders with right-click context menu
- β
Nested Folders - Support for hierarchical folder structures
- β
Text Selection Menu - Right-click on selected text to ask questions or get explanations
- β
Ephemeral Completions - Ask/Explain responses don't clutter chat history
- β
Full Localization - All Ask & Explain features translated to 10 languages
- β
Unit Tests - Complete test coverage for new components
$3
- β
Chat Export - Export conversations to PDF, TXT, and JSON formats
- β
Active Chat Protection - Prevent accidental deletion of the currently active chat
- β
Markdown Improvements - Better list indentation and search preview rendering
- β
UI Polish - Fixed search modal dimensions and sidebar localization
- β
Bug Fixes - Immediate chat list updates and various stability improvements
$3
- β
Voice Input - Record audio messages with automatic transcription
- β
Real-time Spectrogram - Visual feedback during recording
- β
Multi-language Transcription - Support for multiple languages
$3
- β
Response Actions - Continue, regenerate, and rate responses
- β
Rating System - Comprehensive feedback with good/bad ratings
$3
- β
File Upload Support - Attach files to messages with UI
- β
Socket.IO Streaming - Real-time WebSocket communication
- β
Smart Completion Detection - Handles multiple finish signal types
- β
Conversation History - AI remembers all previous messages
- β
Chat History Persistence - Full conversation saved to OpenWebUI server
- β
Completion Finalization - Proper /api/chat/completed endpoint integration
- β
Duplicate Prevention - Fixed duplicate API calls and messages
- β
Correct API Flow - Proper sequence: update chat β completions β update chat β completed
- β
Message Structure - Correct parentId/childrenIds relationships
- β
Model Item Support - Full model metadata in requests
- β
Angular 2025 - Zoneless, signals, modern architecture
- β
File Separation - TS/HTML/SCSS split
- β
messagesChanged Event - Track message count
- β
inject() DI - Modern dependency injection
- β
SCSS Styling - Modern CSS with nesting
- β
Async/Await - Modern API patterns
$3
- β
Basic chat functionality
- β
Markdown rendering
- β
Streaming responses
- β
Multi-language support
File Upload
The component supports file attachments:
`typescript
// Files are automatically uploaded when selected
// They appear in the UI with filename and size
// Click Γ to remove before sending
`
Supported workflow:
1. Click + button in input area
2. Select "Upload Files" from menu
3. Choose file to upload
4. File appears in preview area
5. Send message - file is attached automatically
Files are sent to OpenWebUI API and processed according to the model capabilities.
Response Interaction Controls
The component provides interactive controls for each assistant response:
$3
Every assistant message displays action buttons:
- Continue - Extend incomplete responses
- Regenerate - Generate alternative responses with options:
- Custom input with text field
- Try Again (resend previous prompt)
- More Concise
- Add Details
- Rate Good π - Provide positive feedback
- Rate Bad π - Provide negative feedback
Visibility:
- Latest message: Always visible
- Previous messages: Visible on hover
$3
Comprehensive feedback system with two rating types:
#### Good Rating (π)
When rating a response as good, you can select from:
- Accurate information
- Followed instructions perfectly
- Showcased creativity
- Positive attitude
- Attention to detail
- Thorough explanation
- Other
#### Bad Rating (π)
When rating a response as bad, you can select from:
- Don't like the style
- Too verbose
- Not helpful
- Not factually correct
- Didn't fully follow instructions
- Refused when it shouldn't have
- Being lazy
- Other
Features:
- Detailed Ratings - 1-10 scale with tags and comments
- Pre-population - Edit existing ratings by clicking the rating button again
- Confirmation - "Thank you for your feedback" message after submission
- Persistence - Ratings saved to OpenWebUI server with full context
$3
Extend incomplete or truncated responses:
`typescript
// Automatically continues from where the response stopped
// Maintains conversation context
// Updates the same message with additional content
`
$3
Generate alternative responses with multiple options:
`typescript
// Try Again - Resend the same prompt for a different response
// More Concise - Request a shorter version
// Add Details - Request more comprehensive information
// Custom Input - Provide specific instructions for regeneration
`
Voice Input
The component supports voice recording with automatic transcription:
$3
- π€ Voice Recording - Click microphone button to start recording
- π Real-time Spectrogram - Visual feedback showing audio frequency during recording
- π΄ Stop Recording - Click stop button to end recording
- βοΈ Auto-transcription - Audio automatically transcribed to text via OpenWebUI API
- βοΈ Editable Text - Review and edit transcribed text before sending
- π Multi-language - Transcription supports multiple languages
- β οΈ Error Handling - Clear error messages for permission issues or failures
$3
1. Click microphone button near the send button
2. Grant microphone permission when prompted by browser
3. See spectrogram visualization showing your voice in real-time
4. Click stop button when finished recording
5. Wait for transcription - audio is sent to OpenWebUI API
6. Review transcribed text in the input field
7. Edit if needed and send your message
$3
Voice input requires:
- Modern browser with Web Audio API support (Chrome, Firefox, Safari, Edge)
- Microphone permission granted by user
- HTTPS connection (required for microphone access)
$3
The component handles various error scenarios:
- Browser not supported - "Your browser doesn't support voice recording"
- Permission denied - "Microphone permission denied. Please enable it in your browser settings"
- Recording failed - "Failed to record audio. Please try again"
- Transcription failed - "Failed to transcribe audio. Please try again" with retry button
$3
- Audio Format: WebM with Opus codec
- Sample Rate: 48kHz (Web Audio API standard)
- API Endpoint: /api/v1/audio/transcriptions
- Visualization: Real-time FFT analysis with frequency bars
- Cleanup: Automatic microphone release after recording
Ask & Explain Feature
The component includes an interactive context menu for selected text:
$3
1. Select text in any chat message
2. Right-click to open the context menu
3. Choose:
- Ask - Type a custom question about the selected text
- Explain - Get an instant AI explanation
$3
- π¬ Context Menu - Clean, positioned menu on right-click
- β Ask Mode - Input field for custom questions
- π Explain Mode - Instant explanations without additional input
- π¨ Modal Interface - Beautiful modal for displaying responses
- π Markdown Rendering - Formatted AI responses
- β‘ Streaming - Real-time response generation
- π Localized - Full translation support
- π Ephemeral - Responses don't persist in chat history
$3
`
User selects: "Angular signals are reactive primitives"
Right-clicks β Explain
AI Response (in modal):
"Angular signals are a new reactive state management system..."
`
Folder Support
Organize your conversations efficiently with folders:
$3
- π Create Folders - Group related chats together
- π±οΈ Drag & Drop - Easily move chats into folders
- π Nested Structure - Create subfolders for better organization
- βοΈ Manage - Rename or delete folders via context menu
$3
1. Enable Folders: Set [folders]="true" in your component
2. Create Folder: Click the "New Folder" button in the sidebar
3. Move Chats: Drag and drop chats into folders
4. Context Menu: Right-click folders to manage them
`typescript
[folders]="true"
...>
`
Tools Support
Access and enable server-side tools from the Open WebUI API:
$3
- π οΈ Tools Menu - Access tools via the "+" dropdown menu
- β
Selection - Select/deselect tools with visual checkmarks
- π΅ Tool Indicator - Badge showing enabled tools in input area
- β‘ Prefetch - Tools list prefetched on init for faster display
- π API Integration - Selected tool IDs sent in completion requests
$3
1. Enable Tools: Set [tools]="true" in your component
2. Access Menu: Click "+" button and select "Tools"
3. Select Tools: Click tools to toggle selection
4. Send Message: Selected tools are automatically included in requests
`typescript
[tools]="true"
...>
`
$3
1. Component fetches available tools from /api/v1/tools/
2. Tools appear in a submenu with name and description
3. Selected tools show a checkmark indicator
4. Tool indicator badge appears when tools are enabled
5. tool_ids array is included in completion request payload
Reference Chat Support
Reference previous conversations to provide context for new messages:
$3
- π¬ Reference Chat Menu - Access via the "+" dropdown menu
- π Chat Selection - Browse and select from existing chats
- π·οΈ Visual Indicator - Referenced chats appear as badges in input area
- βΎοΈ Pagination - Load more chats with infinite scroll
- π API Integration - Referenced chat IDs included in completion requests
$3
1. Enable Reference Chats: Set [showReferenceChats]="true" in your component
2. Access Menu: Click "+" button and select "Reference Chat"
3. Select Chat: Click a chat to reference it
4. Send Message: Referenced chat context is automatically included
`typescript
[showReferenceChats]="true"
...>
`
$3
1. Click "+" button and select "Reference Chat"
2. Browse available chats with pagination support
3. Select a chat to reference - it appears as a badge
4. Send your message - the referenced chat provides context
5. AI can access the referenced conversation for better responses
Reference Notes Support
Reference notes to provide context for new messages:
$3
- π Reference Note Menu - Access via the "+" dropdown menu
- π Note Selection - Browse and select from existing notes
- π·οΈ Visual Indicator - Referenced notes appear as badges in input area
- π API Integration - Referenced note IDs included in completion requests
$3
1. Enable Reference Notes: Set [showReferenceNotes]="true" in your component
2. Access Menu: Click "+" button and select "Reference Note"
3. Select Note: Click a note to reference it
4. Send Message: Referenced note context is automatically included
`typescript
[showReferenceNotes]="true"
...>
`
$3
1. Click "+" button and select "Reference Note"
2. Browse available notes
3. Select a note to reference - it appears as a badge
4. Send your message - the referenced note provides context
5. AI can access the referenced note content for better responses
Web Page Attachment
Process and attach web page content to your messages:
$3
- π Web Page Processing - Extract and process web page content via OpenWebUI API
- π₯ Attachment Menu - Access via the "+" dropdown menu alongside file upload
- π API Integration - Uses /api/v1/retrieval/process/web endpoint
- π·οΈ Visual Indicator - Attached web pages appear as badges in input area
- π Multi-language - Full translation support in 10 languages
- ποΈ Conditional Display - Enable/disable via showAttachWebPage property
$3
1. Enable Feature: Set [showAttachWebPage]="true" in your component
2. Access Menu: Click "+" button and select "Attach Web Page"
3. Enter URL: Paste the web page URL in the modal dialog
4. Process Content: Click "Attach" to process the web page
5. Send Message: The web page content is automatically included
`typescript
[showAttachWebPage]="true"
...>
`
$3
1. Click "+" button and select "Attach Web Page"
2. Enter a valid web page URL in the modal dialog
3. The URL is sent to /api/v1/retrieval/process/web endpoint
4. OpenWebUI processes the web page content
5. Processed content is attached as a file-like object
6. Send your message - the web page content provides context
7. AI can access the processed web page content for better responses
$3
`typescript
// User attaches: https://example.com/article
// System processes and includes content in message context
// AI can reference the article content in responses
`
$3
- Invalid URLs are rejected with clear error messages
- Network errors are displayed with retry options
- Processing failures show descriptive error messages
- All errors are translated in 10 languages
Archived Chats
Access and manage your archived conversations with the archived chats modal:
$3
- ποΈ View Archived - Dedicated modal to access all archived chats
- π Search - Search through archived chats with debounced query
- π€ Unarchive - Restore chats to your main chat list
- ποΈ Delete - Permanently delete archived chats with confirmation
- βΎοΈ Pagination - Load more with infinite scroll
- β¨οΈ Keyboard Navigation - Focus trap and ESC to close
$3
1. Enable History: Set [history]="true" to enable chat sidebar
2. Archive Chats: Right-click any chat and select "Archive"
3. View Archived: Click "Archived Chats" in the sidebar header
4. Manage: Search, unarchive, or delete from the modal
`typescript
[history]="true"
...>
``