Open WebUI Chat Widget

Embeddable chat widget for Open WebUI with knowledge base support. Use it as a Web Component or in Vue 3. All requests go through your backend so the API key never touches the browser.

• No API key in the frontend – your backend proxies requests to Open WebUI.
• Web Component or Vue 3 (or script tag).
• Configurable: proxy URL, model, knowledge bases, title, logo, color.

---

Backend proxy required

The widget only talks to your backend. Your backend adds the Open WebUI API key and forwards requests.

Browser (widget)  →  Your backend (API key in .env)  →  Open WebUI

This repo includes a reference proxy (Python/FastAPI) you can copy or adapt.

---

Installation

Widget (Web Component):

npm install @halfcross/open-webui-chat-widget

Vue 3 wrapper (optional):

npm install @halfcross/open-webui-chat-widget-vue

If you use GitHub Packages, add an .npmrc in your project:

@halfcross:registry=https://npm.pkg.github.com

---

Usage

Web Component

<owui-chat-widget
  proxy-url="https://your-app.com/api/owui-chat"
  title="Chat"
  primary-color="#2563eb"
  position="bottom-right"
></owui-chat-widget>
<script type="module" src="node_modules/@halfcross/open-webui-chat-widget/dist/owui-widget.js"></script>

With a script tag (IIFE): use owui-widget.script.iife.js and set attributes with data-proxy-url, data-title, etc.

Vue 3

<template>
  <OwuiChatWidget
    proxy-url="/api/owui-chat"
    title="Chat"
    :knowledge-base-ids="['kb-id-1']"
    position="bottom-right"
  />
</template>
<script setup>
import { OwuiChatWidget } from "@halfcross/open-webui-chat-widget-vue";
</script>

---

Configuration

Attribute / prop	Description
proxy-url	Required. Your backend proxy URL.
model	Open WebUI model name.
knowledge-base-ids	Knowledge base IDs (array or JSON string).
citation-sources	Optional list for citations: [{ "index": 1, "title": "Doc", "url": "https://..." }].
file-base-url	Base URL for document links when the API returns sources (e.g. your Open WebUI URL).
context	Optional context (e.g. username, page) sent as a system message; not shown in the UI.
title	Header title.
logo-url	Logo image URL.
primary-color	Accent color (e.g. #2563eb).
position	bottom-right, bottom-left, or inline.

When Open WebUI returns sources (e.g. with RAG), the widget shows a "Sources" list and turns [1], [2] in the text into links or tooltips if you set file-base-url or citation-sources.

---

Try the demo

You can run the included demo against your own Open WebUI instance:

1. Backend – from the repo root:

   cd apps/demo/backend
   python3 -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   cp .env.example .env

   Edit .env: set OWUI_BASE_URL and OWUI_API_KEY (from Open WebUI → Settings → Account → API Keys).

   python -m uvicorn main:app --reload --port 8765

2. Frontend – in another terminal:

   cd apps/demo
   pnpm install && pnpm run dev

Open http://localhost:5173. The demo proxy has no auth; use only for local testing.

---

Build from source

If you want to build the widget yourself instead of installing from the registry:

git clone https://github.com/halfcross/open-webui-chat-widget.git
cd open-webui-chat-widget
pnpm install
pnpm run build

• Widget: built output is in packages/widget-core/dist/ (use owui-widget.js or owui-widget.script.iife.js).
• Vue package: packages/vue/dist/. The Vue package depends on the widget; point your app at the local widget build or publish the widget first and depend on it by version.

---

License

MIT.