[RFC] OpenSearch Dashboards Banner Plugin

[sidwang42]

RFC: Dashboard Banners UI Plugin for OpenSearch Dashboards

Proposal

Introduce a standalone UI plugin to provide a global, configurable header banner system in OpenSearch Dashboards (OSD). Unlike the existing core banner system, this plugin is dedicated to top-of-page announcements, offering styling, markdown, dismissal, and configuration capabilities. While Phase 1 may appear functionally similar to the current core banner service, the key distinction is architectural: this plugin is not designed for reuse by other plugins and affects layout and configuration scopes that go beyond temporary notifications.

Background

The existing core OverlayBannersService was built to support temporary, client-only notifications within the main body of the OSD layout. Extending it to support global banners would introduce significant risk and complexity:

1. Separation of Concerns: The core service's implementation is tightly coupled with existing layout logic and expectations. Altering it to support global banners, custom styling, and content types introduces branching logic and degrades its clarity.

2. Widespread Usage: The core banner system is already used by several plugins, including data source management. Modifying its behavior (e.g., adding support for a new banner location or styling) could lead to regressions.

3. Scope Differences: The global banner is intended to be persistent and not tied to plugin behavior or runtime logic. It may also eventually require server-side logic (e.g., fetching banner content from external links), which the client-only core banner system cannot support.

4. Ownership and Lifecycle: The banner plugin manages its own configuration and rendering lifecycle. This isolates it from the OSD core and improves maintainability, versioning, and backporting.

The plugin model also allows the system to evolve—such as integrating with feature flags or server routes—without impacting unrelated parts of Dashboards.

Terminology

• Header Banner: A persistent, top-of-page banner distinct from ephemeral system notifications.
• Banner Configuration: YAML or Advanced Settings controlling banner content, visibility, and styling.
• Banner Dismissal: Per-user setting to hide the banner, persisted in local storage or Advanced Settings.

Design Considerations

Mount Point and Layout

Because OSD does not currently expose a mount point at the very top of the layout, the plugin will require changes to the core layout (e.g., adding a <div id="globalBanner" /> to header.tsx). This modification is minimal and localized, and allows the plugin to render above the main header.

Potential for Future Expansion

Phase 2 anticipates server-side logic and dynamic sources for banner content. This may include:

• Pulling markdown from a server
• Introducing REST APIs for banner content
• Role-based visibility or scheduled banners

[sidwang42]

cc: @eemijuntunen @seraphjiang @zhongnansu

[ashwin-pc]

Can we add more details to this RFC before opening it? Having a placeholder here serves no purpose.

[ruanyl]

Instead of introducing another plugin, can we extend the current core banner service by introducing location so that user can choose where the banner should be displayed(current location or on the top)?

[sidwang42]

Instead of introducing another plugin, can we extend the current core banner service by introducing location so that user can choose where the banner should be displayed(current location or on the top)?

Thanks for the thoughtful suggestion, @ruanyl!

Here are two main reasons why we choose to introduce another plugin:

1. Separation of Concerns

The core banner service was intentionally designed with a single, focused responsibility: displaying lists of global system level notifications at the top of the page body. Its implementation reflects this constraint:

// Current implementation is tightly coupled to top-of-body rendering
export const BannersList: React.FunctionComponent<Props> = ({ banners$ }) => {
  // ...
  return (
    <div className="osdGlobalBannerList">
      {banners.map((banner) => (
        <BannerItem key={banner.id} banner={banner} />
      ))}
    </div>
  );
};

While our goal here is to display a banner at the top of the page—even above the global headers—reusing the core banner service would require repositioning existing layout elements (like shifting the header content down). This creates visual and structural confusion. Extending this service to support additional locations, text URLs, and style settings would blur its purpose and introduce branching logic that increases complexity and maintenance overhead.

2. Widespread Usage

The core banner service is used by multiple plugins across the codebase. For example, the data source management plugin uses it extensively. Changing the core would require updates to all these consumers, creating a high risk of regressions.

[ruanyl]

Hi @sidwang42

To address your concerns (1) and (2), I propose extending the existing OverlayBannersService in a backward-compatible way, without introducing a new plugin. Here's the approach:

1. Extend OverlayBannersService to support banner type
   We can add a type parameter to the add method, with a default value of 'sub-hero-banner' to preserve existing behavior:

    const service: OverlayBannersStart = {
      // Add a new optional parameter: `type` and the default value is `sub-hero-banner` which align with the existing behavior so it's a non-breaking changes
      add: (mount, priority = 0, type = 'sub-hero-banner') => {
        const id = genId();
        const nextBanner: OverlayBanner = { id, mount, priority, type };
        banners$.next(banners$.value.add(id, nextBanner));
        return id;
      },
      ....
    }

2. Then for the current BannersList, we can do something like this which is again backward compatible:

export const BannersList: React.FunctionComponent<Props> = ({ banners$ }) => {
  const [banners, setBanners] = useState<OverlayBanner[]>([]);
  useEffect(() => {
    // only filter out 'sub-hero-banner' banners
    const subscription = banners$.subscribe((items) =>
      setBanners(items.filter((item) => item.type === 'sub-hero-banner'))
    );
    return () => subscription.unsubscribe();
  }, [banners$]); // Only un/re-subscribe if the Observable changes

  if (banners.length === 0) {
    return null;
  }

  return (
    ...
  );
};

3. Introduce HeroBannersList to support top-of-page banners
   We can then create a separate HeroBannersList component that listens to the same observable but filters for type === 'hero-banner', and mounts it at the top of the page layout.

This approach:

• Keeps all banner logic within the current overlay module
• Avoids introducing a new plugin which potentially will increase future maintenance efforts
• Supports multiple banner type in a scalable way
• Is backward compatible

Let me know what you think :)

[sidwang42]

Hi @ruanyl,

Thanks for the detailed suggestion — it's a thoughtful approach and I appreciate the backward-compatible design.

That said, I still believe a standalone plugin is more appropriate here. Unlike the core OverlayBannersService, which is used by various parts of the system, the header banner is a self-contained feature not intended for reuse across plugins.

Embedding it into the core risks expanding the surface of a service meant for lightweight in-app notifications. The header banner, by contrast, affects global layout, styling, and config — responsibilities better scoped in a dedicated module.

[ruanyl]

Unlike the core OverlayBannersService, which is used by various parts of the system, the header banner is a self-contained feature not intended for reuse across plugins.

1. Can you clarify what do you mean by not intended for reuse across plugins?
2. How can you make it a self-contained feature without modifying core? You would need at least add a mount point to the main application layout for the banner, am I right?

[zhongnansu]

@ruanyl Hi Yulong, The Global OSD banner serves different purposes comparing to the existing core banner service, and that's why we think we should isolate the implementation by building it as a plugin.

1. Global OSD banner is for permanently displaying messages(unless user explicitly turns it off), while core banner service is temporary, and it has to come with a settings lifetime. As the core banner service documentation mentions, it's A custom banner intended for temporary notices to all users

2. Global OSD banner is not intend for being consumed by other plugins, with that being said, no plugins or component should control what and how content is rendered on the banner. Global banner display same content and style across any OSD page, and it shouldn't expose any API. While I assume the existing core banner service expose API through core for other consumers.

3. Fetching content for display can potentially be enriched with complex server side logic, and introduce server side routes. While existing core banner service implementation are all based one client side. E.g, In the future, we could consider integrate with external systems & databases (out of OpenSearch ecosystem)to dynamically set the content of this global OSD banner. This could require logic lives in server side, supported by API routes to make the solution secure and reliable.