Creating a banner to display at the top of your site

[Discourse]

This guide explains different methods to create and customize banners on your Discourse site, from simple dismissible banners to more advanced options.

Required user level: Moderator (Dismissible banner), Administrator

Banners are an effective way to communicate important information to your site visitors. This guide will walk you through various methods to create and customize banners on your Discourse site.

Welcome banner

A welcome banner greets new and returning members with a friendly message and a prominent search bar, making it easy for visitors to quickly find content that they’re looking for.

To enable and customize welcome banner, go to the admin area and select the Appearance > Welcome banner link in the sidebar.

In this area, you’ll find the following settings:

• Enabled on themes…: This lets you designate which of your active themes should display the welcome banner.
• Background image: Upload an image to serve as the background for your welcome banner.
• Text color: If the default text color controlled by your color palette conflicts with your background image, you can select a new color here. Note that this setting only applies when you’ve uploaded a background image.
• Page visibility: This determines which pages display the welcome banner. By default it shows on Top menu pages (meaning the pages selected in the Top menu site setting), but you can change to:
  • Homepage only: The welcome banner only shows on the site homepage (i.e. the first page listed in the Top menu site setting).
  • Discovery pages: The welcome banner shows on all of the Top menu pages, even if they are not shown in the actual top menu of your site (i.e. not selected in the setting).
  • All pages: The welcome banner shows on all pages of your site. This is generally not recommended since it can cause visual clutter on topic pages that distracts members from reading and participating.
• Location: This determines where the welcome banner shows on the page. By default, it shows Above topic content but you can also select Below site header. The difference is a little subtle, and shown in the screenshots below:

You can also customize the welcome banner’s text to change the greeting and add more explanatory text to the welcome banner.

• Header for new members: The primary greeting shown to new members the first time they log in to your site.
• Header for logged-in members: The primary greeting shown to returning members.
• Header for anonymous visitors: The primary greeting shown to anonymous (i.e. not logged in) members.
• Subheader for logged-in members: An optional secondary line of text below the header shown to returning members.
• Subheader for anonymous visitors: An optional secondary line of text below the header shown to anonymous (i.e. not logged in) members.
• Search placeholder: The placeholder text shown in the welcome banner’s search field.

Dismissible banner

A dismissible banner is a temporary notice that users can close. Here’s how to create one:

1. Create or navigate to a topic in any category (public or private). The original post (OP) at the top of the topic will be the source of your banner.
2. Open the admin options by clicking the wrench icon to the right or at the bottom of the topic.
3. Select “Pin Topic…”
4. In the new window, choose Make Banner Topic

The banner will now appear at the top of your site. Users will see a dismissible banner. Staff will also see a link to edit the source topic.

Tips for effective dismissible banners:

• Keep the text clear and concise
• The maximum height is 250px (editable via CSS)
• For longer text, users can scroll within the banner
• Consider adding a link to a relevant, public topic for more information

Permanent banner

To create a banner that’s always visible and can’t be dismissed by users:

1. In your site settings, search for global_notice.
2. Enter your banner text or HTML in this field.

Tips for permanent banners:

• This type of banner is typically used for urgent site communications but can be used for any permanent message
• This banner is visible to everyone, including anonymous users on login_required sites
• The banner can be removed by resetting the global notice site setting

Advanced banners

You can build more advanced banners by using a theme component. Please note that these theme components may conflict with the core welcome banner feature.

Welcome Link Banner

This component allows you to add custom text and 1-4 links to your banner. It offers various customization options, including:

• Choosing where to display the banner (homepage, topic lists, or all pages)
• Adding links with Font Awesome icons
• Limiting visibility based on user trust levels
• Customizing background images or colors
• Adjusting text and icon colors

Versatile Banner

One of the most popular and well-maintained components, the Versatile Banner offers extensive customization options through the interface, including:

• Banner display limited to
  • logged-in or anonymous users
  • mobile or desktop device
  • homepage, topic list, or all pages
• Dismissible, expandable, or persistent options
• Full browser-width setting
• Color management
• Heading and column customization using HTML

Customizing banners with CSS

You can customize all banner types using CSS. For more information on using CSS to customize your Discourse site, see the Beginner’s guide to using Discourse Themes.

Last edited by @lindsey 2025-12-19T13:49:10Z

Check document

Perform check on document:

[leopedrini (Leonardo Zanoni Pedrini)]

@Discourse

Appearance > Themes & components link in the sidebar.

I could not find this option… Is it a new feature in Beta version?

[leopedrini (Leonardo Zanoni Pedrini)]

@leopedrini

I could not find this option… Is it a new feature in Beta version?

Update: after updating from 3.4.6 to 3.5.0, it was visible:

[RBoy]

@Discourse

js.welcome_banner.search — The placeholder text shown in the welcome banner’s search field.

There’s a bug in the build 3.6.0.beta1-dev (e44347414a)

Changing this Site text has no effect on the text in the Search bar, it still always shows Search. Tested on Windows 10 x64 running Chrome

[awesomerobot (Kris)]

Working on a fix for this here: DEV: use welcome_banner.search placeholder in search banner by awesomerobot · Pull Request #34523 · discourse/discourse · GitHub

[RBoy]

Amazing, thank you - that fixed it!

[tknospdr (David Muszynski)]

Having an issue with my background image for the welcome banner.
I’m using Cloudflare R2 S3 buckets for object storage on the site in question.
When I upload a background image in the admin section it shows up correctly, if I click to show it full size it works. And if I right click and show image in new tab it works and using the public bucket URL:
https://eufiles.technospider.com/original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg

What it injects into the CSS though, is this URL:
https://exotics-unlimited.7100e60b936991e069a3230dc05d4976.r2.cloudflarestorage.com/original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg

I have another site that uses local storage and the banner background image works correctly.

Is this a bug in the code, or am I doing something wrong?

After digging around some more it looks like this CSS controls the background image:

If I manually replace the URL in the inspector it works.
I tried overriding that with:

.custom-search-banner-wrap .welcome-banner__wrap {
  background-image: "eufiles.technospider.com/original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg";
}

But that’s not working. Still feels like a bug though.

[yuriy (Yuriy Kurant)]

@tknospdr, I am not quite following what issue are you experiencing?

I checked your site https://eu.technospider.com, and I see that the background image is rendered as expected:

[tknospdr (David Muszynski)]

I think I finally got the CSS override working. The issue is that it shouldn’t need an override.

It appears the banner code is using the wrong asset if you’re hosting with Cloudflare S3.

[yuriy (Yuriy Kurant)]

Which exactly is your override?

On our side, we could make sure we apply only a URL pathname /original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg in CSS:

background-image: url(/original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg)

I believe, this rule would work for you without requiring any overrides?

[tknospdr (David Muszynski)]

@yuriy

Which exactly is your override?

My entire override is:

.welcome-banner {
  background-image: url(//eufiles.technospider.com/original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg);
}
.--with-bg-img .welcome-banner__wrap {
  border-radius: 20px;
}
.welcome-banner__title {
  font-size: var(--font-up-4);
  max-width: 900px;
}
.welcome-banner__subheader {
  font-size: 17px;
  padding-bottom: 20px;
}

On our side, we could make sure we apply only a URL pathname /original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg in CSS:

background-image: url(/original/1X/609c9563f4d8c7d229b495a2cb967782a63aa2df.jpeg)

I believe, this rule would work for you without requiring any overrides?

In the UI, all I can do is upload an image, so I believe that a code change is needed to be able to remove my CSS override statement.
Would be happy to try out whatever fixes you care to implement.