From 1f8c11b67cf9260879dd62aa06e4efa4be25b946 Mon Sep 17 00:00:00 2001
From: Classic298 <27028174+Classic298@users.noreply.github.com>
Date: Tue, 3 Mar 2026 13:46:59 +0100
Subject: [PATCH] Update banners.md
---
.../access-security/interface/banners.md | 325 ++++++++++++++----
1 file changed, 264 insertions(+), 61 deletions(-)
diff --git a/docs/features/access-security/interface/banners.md b/docs/features/access-security/interface/banners.md
index 1cf97761..058d39fe 100644
--- a/docs/features/access-security/interface/banners.md
+++ b/docs/features/access-security/interface/banners.md
@@ -5,120 +5,323 @@ title: "Customizable Banners"
## Overview
-Open WebUI allows administrators to display custom banners to logged-in users. This feature is useful for making announcements, displaying system-wide alerts, or sharing important information. Banners are persistent and can be configured to be dismissible by users.
+Open WebUI allows administrators to display custom banners to logged-in users. Banners are useful for announcements, system-wide alerts, maintenance notices, and other important messages.
-You can configure banners in two ways: through the Admin Panel for a user-friendly experience, or via environment variables for automated or GitOps-style deployments.
+Banners are persistent and can optionally be **dismissible** by users. You can configure banners in two ways:
-## Configuring Banners
+1. **Admin Panel** (recommended for quick edits and experimentation)
+2. **Environment variable (`WEBUI_BANNERS`)** (recommended for automated / GitOps-style deployments)
+
+---
+
+## When to use banners
+
+Banners are best for short, high-visibility messages such as:
+
+- Scheduled maintenance and planned downtime windows
+- Incident notifications (degraded performance, partial outages)
+- Policy reminders (acceptable use, data handling, retention)
+- Major changes (new models, feature rollouts, UI changes)
+- Links to your internal comms channels for updates and Q&A
+
+**Tip:** Keep banners concise and link to more detailed information (status page, release notes, support channel).
+
+---
+
+## Configuring banners
### Option 1: Using the Admin Panel
-This is the most straightforward way to manage banners.
+This is the most straightforward way to manage banners:
-1. **Log in** to your Open WebUI instance as an administrator.
-2. Navigate to the **Admin Panel** > **Settings** > **General**.
-3. Locate the **"Banners"** section.
-4. Click the **+** icon to add a new banner.
+1. Log in to your Open WebUI instance as an administrator.
+2. Navigate to **Admin Panel** → **Settings** → **General**.
+3. Locate the **Banners** section.
+4. Click the **+** icon to add a new banner.
+5. Click **Save** to apply your changes.
-You can then configure the following options for each banner:
+You can configure the following options for each banner:
-- **Type:** The color and style of the banner. Choose from:
- - `info` (Blue)
- - `success` (Green)
- - `warning` (Yellow)
- - `error` (Red)
-- **Title:** The main heading of the banner.
-- **Content:** The main text or message of the banner.
-- **Dismissible:** If toggled on, users can close the banner. Dismissed banners are stored in the user's browser, so they will not reappear for that user unless their browser cache is cleared. If toggled off, the banner will always be visible.
+- **Type:** The color and style of the banner:
+ - `info` (Blue)
+ - `success` (Green)
+ - `warning` (Yellow)
+ - `error` (Red)
+- **Title:** The main heading of the banner.
+- **Content:** The main message (HTML only).
+- **Dismissible:** If enabled, users can close the banner.
-5. Click **"Save"** at the bottom of the page to apply your changes.
+#### How dismissing works
-### Option 2: Using Environment Variables
+Dismissed banners are stored in the user’s browser (client-side). This means:
-For automated deployments, you can configure banners using the `WEBUI_BANNERS` environment variable. The variable should be a JSON string representing a list of banner objects.
+- A dismissed banner may reappear if the user clears site data / cache
+- A dismissed banner may reappear on a different device or browser
+- Dismissal is per-banner `id` (if the `id` changes, the banner is treated as new)
-**Environment Variable:**
+If you need the banner to remain visible for everyone, set `dismissible: false`.
-- `WEBUI_BANNERS`
- - **Type:** `string` (containing a JSON list of objects)
- - **Default:** `[]`
- - **Description:** A list of banner objects to be displayed to users.
+---
-**Example:**
+### Option 2: Using environment variables (`WEBUI_BANNERS`)
-Here is an example of how to set the `WEBUI_BANNERS` variable in a `docker-compose.yml` file:
+For automated deployments, configure banners using the `WEBUI_BANNERS` environment variable. The value must be a **JSON string** representing a **list** (array) of banner objects.
+
+**Environment variable:**
+
+- `WEBUI_BANNERS`
+ - **Type:** `string` (containing a JSON list of objects)
+ - **Default:** `[]`
+ - **Description:** A list of banner objects to be displayed to users
+
+#### Example (Docker Compose)
```yaml
services:
open-webui:
image: ghcr.io/open-webui/open-webui:main
environment:
- - 'WEBUI_BANNERS=[{"id":"update-2024-07-26","type":"info","title":"System Update","content":"A system update is scheduled for this Friday at 10 PM. Expect brief downtime.","dismissible":true},{"id":"policy-reminder","type":"warning","title":"Policy Reminder","content":"Please remember to adhere to the company-wide usage policy.","dismissible":false}]'
+ - 'WEBUI_BANNERS=[{"id":"maintenance-2026-03","type":"warning","title":"Maintenance","content":"A maintenance window is planned this week. Expect brief interruptions. See status page.","dismissible":true,"timestamp":1772500000}]'
```
-## Banner Object Properties
+> Note: Because `WEBUI_BANNERS` is a JSON string inside YAML, you must ensure it remains valid JSON (see "Common pitfalls" below).
-Each banner object in the JSON list has the following properties:
+---
-- `id` (string, required): A unique identifier for the banner. This is used to track which banners a user has dismissed.
-- `type` (string, required): The style of the banner. Must be one of `info`, `success`, `warning`, or `error`.
-- `title` (string, optional): The title text displayed on the banner.
-- `content` (string, required): The main message of the banner.
-- `dismissible` (boolean, required): Determines if the user can close the banner. `true` means it can be dismissed; `false` means it cannot.
-- `timestamp` (integer, required): **Note:** While this field is present in the configuration, it is not currently used by the frontend. The timestamp does not affect whether a banner is displayed or not.
+## Banner object properties
-## Supported Content Formatting
+Each banner object supports the following properties:
-Banner content supports a subset of **HTML only** — Markdown syntax is not rendered. The following elements work in the `title` and `content` fields:
+- `id` (string, required): Unique identifier for the banner. Used to track whether a user has dismissed it.
+- `type` (string, required): Banner style. Must be one of: `info`, `success`, `warning`, `error`.
+- `title` (string, optional): Title text.
+- `content` (string, required): Main banner message (HTML only).
+- `dismissible` (boolean, required): Whether the user can dismiss the banner.
+- `timestamp` (integer, required): Present in configuration, but currently not used by the frontend to control display timing.
-### Text Formatting
+### Recommended `id` strategy (important)
+
+Pick an `id` format that supports safe updates and avoids accidental re-showing or permanent hiding:
+
+- Stable `id` for small text edits: `policy-reminder`
+- Versioned `id` for "show again to everyone" updates: `incident-2026-03-06-v2`
+- Time-bucketed `id` for recurring events: `maintenance-2026-03`
+
+If users dismissed a banner and you want them to see an updated message, change the `id`.
+
+---
+
+## Supported content formatting (HTML only)
+
+Banner `title` and `content` support a subset of **HTML only** — Markdown syntax is not rendered. Unsupported tags may render as plain text or break the layout.
+
+### Text formatting
| HTML | Effect |
-|------|--------|
-| `` / `` | **Bold** |
-| `` / `` | *Italic* |
+| --- | --- |
+| `` / `` | Bold |
+| `` / `` | Italic |
| `` | Underline |
-| `` / `` | ~~Strikethrough~~ |
+| `` / `` | Strikethrough |
| `` | Highlight |
| `` | Slightly smaller text |
| `` / `` | Subscript / Superscript |
-| `` / `` | `Monospace inline code` |
+| `` / `` | Monospace inline code |
| `` | Hover tooltip |
### Structure
| HTML | Effect |
-|------|--------|
+| --- | --- |
| `
` or literal newlines | Line break |
| `
` | Horizontal rule |
| `Click
...
` | Inline image |
-### Custom Styling
+### Custom styling
-Any inline `style=""` attribute works on allowed tags:
+Inline styles are supported on allowed tags:
```html
-Colored text
-Size override
-Gradient
+Colored text
+Heavier weight
+Gradient background
```
-:::warning Unsupported Content
-Headings (``–``), lists (``, ``), tables, blockquotes, and **Markdown syntax** are not supported — they either render as plain text or break the layout.
-:::
+> Keep styling minimal. Overly large padding, font sizes, or complex layouts can cause banners to become tall or visually inconsistent across themes.
+
+---
+
+## Unsupported content
+
+The following are not supported in banners and may render as plain text or break the layout:
+
+- Headings (``–``)
+- Lists (``, ``)
+- Tables
+- Blockquotes
+- Markdown syntax
+
+If you need "list-like" content, use short lines separated by `
`.
+
+---
+
+## Common pitfalls (and how to avoid them)
+
+### 1) Unexpected spacing from literal newlines
+
+Banner content treats **literal newlines** as line breaks. If you paste nicely formatted/indented HTML with many line breaks, the banner may appear much taller than expected.
+
+**Recommendation:**
+- Use `
` deliberately, and keep the raw HTML relatively compact.
+- Avoid adding blank lines unless you truly want extra spacing.
+
+### 2) Broken links in banner content
+
+If a link appears "broken" or the rest of the banner becomes clickable, it’s usually due to invalid HTML.
+
+Use this exact pattern:
+
+```html
+Open link
+```
+
+**Recommendations:**
+- Always close anchor tags with `
`.
+- Use `target="_blank"` (underscore included).
+- If your URL contains query parameters, escape `&` as `&` inside the `href` attribute:
+ ```html
+ Example
+ ```
+- If you need guaranteed underlining, wrap link text with ``:
+ ```html
+ Support
+ ```
+
+### 3) JSON/YAML escaping issues in `WEBUI_BANNERS`
+
+When using `WEBUI_BANNERS`, you are embedding JSON inside a YAML string (or a shell string). Common problems include:
+
+- Unescaped double quotes inside the JSON
+- Line breaks inserted into the JSON string
+- Copy/paste "smart quotes" (typographic quotes) instead of normal `"`
+
+**Recommendations:**
+- Validate the JSON in a JSON validator before deploying.
+- Keep `content` strings simple; avoid unescaped `"` characters.
+- Prefer using `\"` for quotes inside JSON strings if needed.
+- Check server logs if the banner does not appear.
+
+### 4) Overusing ``
+
+`` is useful for secondary text, but wrapping large parts of the banner in `` can make content hard to read.
+
+**Recommendation:** Use normal text for the main message and reserve `` for less important details.
+
+### 5) External images
+
+Images can be embedded via `![]()
`, but external images may:
+- Fail to load due to network restrictions
+- Create inconsistent sizes across devices if not constrained
+- Introduce privacy/security concerns if loaded from third-party domains
+
+**Recommendations:**
+- Prefer internal/static assets when possible.
+- Always set explicit `width` and `height`.
+- Keep icons small (e.g., 16×16) to avoid increasing banner height.
+
+---
+
+## Reusable patterns (copy/paste snippets)
+
+### Pattern: Minimal two-line announcement with a link
+
+```html
+Notice
+Service updates: Status page
+```
+
+### Pattern: Compact "label" chip (date/impact tag)
+
+```html
+
+ Scheduled
+
+```
+
+### Pattern: Collapsible details (keep banners short)
+
+```html
+Planned update
+
+ More details
+
+ This update may cause brief interruptions during the deployment window.
+
+```
+
+---
+
+## Operational best practices
+
+### Keep banners scannable
+
+A good banner is typically:
+- A short title
+- One sentence describing the situation
+- One link for details and one link for questions (if needed)
+
+### Use banner types consistently
+
+To reduce alert fatigue, consider a consistent mapping:
+- `info`: general announcements
+- `success`: completed changes / resolved incidents
+- `warning`: planned maintenance or partial degradation
+- `error`: active incident / outage
+
+### Remove expired banners
+
+If you keep adding banners without removing old ones, users may ignore them. Remove or replace banners after the event is over.
+
+---
## Troubleshooting
-- **Banner Not Appearing:**
- - Ensure the JSON format for the `WEBUI_BANNERS` environment variable is correct. It must be a valid JSON array of objects.
- - Check the Open WebUI server logs for any errors related to parsing the `WEBUI_BANNERS` variable.
-- **Banner Cannot Be Dismissed:**
- - Verify that the `dismissible` property for the banner is set to `true` in your configuration.
- - If a banner is not dismissible, it is by design and cannot be closed by the user.
+### Banner not appearing
+
+- Ensure `WEBUI_BANNERS` is a valid JSON **array** of objects (not a single object).
+- Check the server logs for parsing errors related to `WEBUI_BANNERS`.
+- If using Admin Panel, confirm you clicked **Save**.
+
+### Banner cannot be dismissed
+
+- Verify that `dismissible` is set to `true`.
+- If `dismissible` is `false`, the banner is intentionally always visible.
+
+### Banner layout looks broken or too tall
+
+- Remove extra blank lines and indentation from the raw HTML.
+- Avoid unsupported HTML (lists, tables, headings).
+- Reduce aggressive inline styles (large `padding`, large `font-size`).
+
+---
+
+## FAQ
+
+### Can I use Markdown in banner content?
+
+No. Banner content supports **HTML only**. Markdown syntax is not rendered.
+
+### Does `timestamp` control when a banner shows?
+
+No. The `timestamp` field is currently not used by the frontend to control whether a banner is displayed. If you need time-based behavior, manage it via your deployment automation (add/remove banners on a schedule).
+
+### Can I show content in multiple languages?
+
+Yes. You can include multiple languages in `content`. If you want to keep the banner short, place the secondary language in a `` block.