Deprecating the Search Banner theme component

Announcements
1

Over the past few months, we have been working on a welcome banner feature that is part of Discourse’s core product. This core welcome banner feature greets new and returning visitors to your community and makes it easy for them to search for content that’s relevant to their needs and interests. With this new core banner in place, we are now deprecating the Search Banner theme component to reduce the complexity of our product offerings and ensure all Discourse users benefit from continued improvements to the core feature.

In this topic, we’ll cover what deprecation means for current users of the Search Banner theme component.

If you are a hosted customer…

We will begin migrating hosted customers from the Search Banner component to the welcome banner feature on 20 November 2025. If you’re currently using this component, you’ll receive a message with the exact timing details for your plan tier.

This migration will copy over any site texts that you’ve updated for the theme component (i.e. search_banner.headline, search_banner.subhead, search_banner.search_button_text) and the values for the show on, plugin outlet, and background image theme component settings into the core feature settings.

Our goal is to minimize the visible impact of this move, so that the banner created by the core feature looks the same as the banner created by the theme component. Communities with an image on their banner may notice a slight shift in its positioning which can be addressed by cropping the image to center the content you want to appear in the banner.

After this migration, the theme component will be disabled and can be safely deleted from the Themes & components page (/admin/config/customize/components).

If you are a self-hosted user…

You should plan to migrate yourself from the theme component to the core feature by 15 December 2025. You can do this manually or using our provided script.

Manual migration

Here’s a map of how the Search Banner theme component’s site texts and settings relate to the same features for the core welcome banner:

Setting description Search Banner theme component Welcome Banner core feature
The heading text shown on the welcome banner. search_banner.headline site text js.welcome_banner.header.anonymous_members and js.welcome_banner.header.logged_in_members site texts
The subheading text shown on the welcome banner. search_banner.subhead site text js.welcome_banner.subheader.anonymous_members and js.welcome_banner.subheader.logged_in_members site texts
The text used for the search button on the banner. * search_banner.search_button_text site text js.welcome_banner.search_placeholder site text
Setting to determine which pages display the welcome banner. show on theme component setting Welcome banner page visibility site setting
Setting to determine where on the page the welcome banner appears. plugin outlet theme component setting Welcome banner location site setting
Background image used on the welcome banner. background image light theme component setting Welcome banner image site setting

* Note that the core welcome banner feature doesn’t support an explicit search button, so we recommend mapping this text to the customizable search field placeholder text for a similar result.

Script migration

Migration consists of three rake tasks that must be run in the following order:

  1. Migrate component settings:
    themes:advanced_search_banner:1_migrate_settings_to_welcome_banner
  2. Migrate component translations:
    themes:advanced_search_banner:2_migrate_translations_to_welcome_banner
  3. Enable core banner, exclude component from themes where it is used, and disable component:
    themes:advanced_search_banner:3_exclude_and_disable

Files <random_name>.sh to be run in container:

  1. task_1.sh:
#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:1_migrate_settings_to_welcome_banner
  1. task_2.sh:
#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:2_migrate_translations_to_welcome_banner
  1. task_3.sh
#!/bin/bash

cd /var/www/discourse && rake themes:advanced_search_banner:3_exclude_and_disable

It is recommended to run each rake task individually for better control over the migration process.

A convenience task themes:advanced_search_banner:migrate_all is also available to run all three sequentially, but use it at your own discretion.

7 Likes
2

Do you mean something like this?

#!/bin/bash
cd /var/www/discourse && rake themes:advanced_search_banner:migrate_settings_to_welcome_banner  && rake themes:advanced_search_banner:migrate_translations_to_welcome_banner &&  rake themes:advanced_search_banner:exclude_and_disable

I don’t think many self-hosters will infer that from <task_1_2_or_3>

Are these rake tasks likely to fail? Can we just run them all at once? If that’s the case, why not have just one rake task that does them all?

Maybe people want something like this:

docker exec -t app bash -c `cd /var/www/discourse && rake themes:advanced_search_banner:migrate_settings_to_welcome_banner  && rake themes:advanced_search_banner:migrate_translations_to_welcome_banner &&  rake themes:advanced_search_banner:exclude_and_disable`

So for people who don’t understand how to do this, they just lose all of their old settings and customized text, right?

What about the people who don’t upgrade again until March? They can still run those rake tasks then? I’m not clear what the importance of 15 December is.

3 Likes
5

I’ll let my colleague who created the script help with the first part of your question, but for the last two questions:

No.

The script is one option; manual migration is another option. That is why we provided very clear descriptions of how the theme component’s settings / strings map to the welcome banner’s settings / strings.

December 15 is when we are completing our migration of hosted customers and when we will officially stop supporting / maintaining the Search Banner component. We are recommending that other users of this component migrate before then so they’re not caught off guard when the theme component becomes incompatible with Discourse core in the future.

If folks choose to wait until later, they should still be able to run these tasks or perform the migration manually, but in the meantime they will be running an unsupported theme component.

4 Likes
6

Correct, the provided command will run all three tasks one after the other. Please note we prefixed each task with a number to indicate the intended execution order.

Thanks, we have updated the Script migration section to make it clearer.

We cannot guarantee 100% success, but we have ensured failures are highly unlikely.

Yes, we have added a convenience task: themes:advanced_search_banner:migrate_all.

2 Likes
7

Awesome! I think that’ll help a lot. People like us don’t mind running a handful of take tasks inside a container, but most self-hosters, not so much.

If it were possible to update the theme component to have a depreciation link on the admin panel that pointed here, then that would help them know this topic exists.

What I’d like to do is find a way to find out if the theme component is installed, preferably from the api. I guess that’ll be to pull the theme component json, run it through jq and filter on the component name. I think that should work, and my dashboard has an api key. Then I can have ansible run the rake task inside the container!

2 Likes
8

Are the official themes that automatically install the component changed beforehand so that no one installs the component without realizing they need to manually configure the welcome banner in core for the theme to work in the future?

2 Likes