Widget Settings | Onpane Docs

Configure these options in your project's Settings page on the Onpane dashboard. Changes take effect immediately for new page loads.

Settings Reference

Setting	Options	Description
Position	Top, Bottom	Where the announcement bar appears on the page
Display Mode	Overlay, Push	Overlay floats over content; Push moves page content to make room
Scroll Behavior	Fixed, Absolute	Fixed stays visible on scroll; Absolute scrolls with page (overlay mode only)
Animation	Slide, Fade, None	Entry animation when the announcement appears. Respects `prefers-reduced-motion`
Font Size	Small, Medium, Large	Proportional text scaling for all announcement elements
Content Max Width	CSS length value (e.g. 1200px, 72rem)	Optional. Constrains inner content width while keeping bar full-width. Content is centered. Common values: 1200px, 960px, 72rem. Has no effect on mobile viewports (below 768px). Override via CSS: `--onpane-content-max-width`
Dismissal Duration	Session, 1 hour, 1 week, 1 month, Forever	How long a dismissal persists before the announcement reappears. Session uses sessionStorage; all others use localStorage
Custom Font	Font family name	Optional font override (default: `inherit`). The font must be loaded on your website
Analytics	Enabled, Disabled	Track views, CTA clicks, and dismissals. No cookies or personal data collected

How Settings Are Delivered

Settings are stored on the server and delivered to the widget alongside announcement data via the API. There is no client-side configuration required beyond the install snippet. When you change a setting in the dashboard, the next visitor page load picks up the change automatically.

Display Mode Details

Overlay Mode

The announcement bar uses position: fixed and floats above page content. The Scroll Behavior setting controls whether the bar remains fixed on scroll or scrolls with the page (using position: absolute).

Push Mode

The announcement bar is inserted at the top of the document with position: relative, pushing all page content below it. The Scroll Behavior setting has no effect in Push mode since the bar is part of the document flow.

Custom Placement

By default the widget renders at the top or bottom of the page. For advanced layouts, you can render the widget inside a specific element on your page using a placeholder div. This is useful for embedding announcements inside hero sections, navigation bars, or application shells.

Default Placeholder

Add a div with id="onpane-placeholder" anywhere on your page. The widget automatically detects it and renders inside it instead of appending to the page body.

HTML

<div id="onpane-placeholder"></div>

<script
  src="https://onpane.com/widget/loader.js"
  data-key="onpane_live_YOUR_KEY_HERE"
></script>

Custom Placeholder ID

To use a different element ID, add the data-placeholder attribute to the script tag.

HTML

<div id="my-announcement-area"></div>

<script
  src="https://onpane.com/widget/loader.js"
  data-key="onpane_live_YOUR_KEY_HERE"
  data-placeholder="my-announcement-area"
></script>

Placeholder Styling

For best results, apply these styles to the placeholder's parent container:

position: relative so the widget positions correctly in overlay mode
overflow: hidden to contain slide animations within the placeholder bounds

The widget adapts its positioning mode automatically based on your display mode setting:

In overlay mode, the bar uses position: absolute within the placeholder
In push mode, the bar uses position: relative and takes space in the normal flow

HTML

<div style="position: relative; overflow: hidden;">
  <div id="onpane-placeholder"></div>
</div>

Visibility Fallback

If the placeholder element has display: none, the widget logs a console warning and falls back to default page-level positioning. This means you can conditionally show or hide the placeholder (for example, on certain pages) and the widget will adapt automatically.