open-webui-docs/docs/features/access-security/interface/banners.md

sidebar_position, title

sidebar_position	title
13	Customizable Banners

Overview

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.

Banners are persistent and can optionally be dismissible by users. You can configure banners in two ways:

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:

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 configure the following options for each banner:

• 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.

How dismissing works

Dismissed banners are stored in the user’s browser (client-side). This means:

• 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)

If you need the banner to remain visible for everyone, set dismissible: false.

---

Option 2: Using environment variables (WEBUI_BANNERS)

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)

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    environment:
      - 'WEBUI_BANNERS=[{"id":"maintenance-2026-03","type":"warning","title":"Maintenance","content":"A maintenance window is planned this week. Expect brief interruptions. <a href=\"https://intranet.example.com/status\" target=\"_blank\">See status page</a>.","dismissible":true,"timestamp":1772500000}]'

Note: Because WEBUI_BANNERS is a JSON string inside YAML, you must ensure it remains valid JSON (see "Common pitfalls" below).

---

Banner object properties

Each banner object supports the following properties:

• 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.

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
<b> / <strong>	Bold
<i> / <em>	Italic
<u>	Underline
<s> / <del>	Strikethrough
<mark>	Highlight
<small>	Slightly smaller text
<sub> / <sup>	Subscript / Superscript
<code> / <kbd>	Monospace inline code
<abbr title="tooltip">	Hover tooltip

Structure

HTML	Effect
<br> or literal newlines	Line break
<hr>	Horizontal rule
<details><summary>Click</summary>...</details>	Collapsible section

Links & media

HTML	Effect
<a href="..." target="_blank">	Clickable link
<img src="..." width="16" height="16">	Inline image

Custom styling

Inline styles are supported on allowed tags:

<span style="color: #b91c1c;">Colored text</span>
<span style="font-weight: 600;">Heavier weight</span>
<span style="background: linear-gradient(90deg,#e0f2fe,#fef9c3);">Gradient background</span>

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 (<h1>–<h6>)
• Lists (<ul>, <ol>)
• Tables
• Blockquotes
• Markdown syntax

If you need "list-like" content, use short lines separated by <br>.

---

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 <br> 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:

<a href="https://example.com" target="_blank">Open link</a>

Recommendations:

• Always close anchor tags with </a>.
• Use target="_blank" (underscore included).
• If your URL contains query parameters, escape & as & inside the href attribute:

  <a href="https://example.com/page?x=1&amp;y=2" target="_blank">Example</a>
  

• If you need guaranteed underlining, wrap link text with <u>:

  <a href="https://example.com" target="_blank"><u>Support</u></a>
  

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 <small>

<small> is useful for secondary text, but wrapping large parts of the banner in <small> can make content hard to read.

Recommendation: Use normal text for the main message and reserve <small> for less important details.

5) External images

Images can be embedded via <img>, 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

<b>Notice</b><br>
Service updates: <a href="https://example.com/status" target="_blank"><u>Status page</u></a>

Pattern: Compact "label" chip (date/impact tag)

<span style="display:inline-block;background:#fff3cd;color:#664d03;padding:2px 8px;border-radius:999px;">
  Scheduled
</span>

Pattern: Collapsible details (keep banners short)

<b>Planned update</b><br>
<details>
  <summary>More details</summary>
  <br>
  This update may cause brief interruptions during the deployment window.
</details>

---

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 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 <details> block.