Help recreating a per-category hero banner (image + overlay text) without layout shift

[Steve_John]

Hi all — I’m trying to build a category banner like the screenshot below:

Goal

• Same layout as the mockup: large banner with category-specific background image and overlayed heading/description.
• Smooth load (no flicker/resize), fully responsive.
• Background must be an image unique to each category (not a global CSS style).

What I tried

• Custom JavaScript to inject the image and text. It works, but the image loads first and then resizes, causing janky transitions/layout shift.
• The Category Banner component got me close, but I couldn’t match this exact layout and per-category image requirements.

Ask

• What’s the recommended approach in Discourse to achieve this?
• Any examples or CSS/HTML patterns to reserve space (e.g., fixed aspect-ratio wrapper/object-fit) and avoid CLS?
• Tips for using per-category uploads or theme settings to set the background image cleanly.

Thanks!

[chapoi (Charlie)]

Very crappy demo (and Im not using topic cards) but I think you can easily do this with just the built-in category background image:

If you just add a category background in the category settings

that places the image on the body tag. Maybe then adjust the CSS to something to your liking (my example is 400px):

`+ some tweaks to text-alignment, you should get an approximation of what you want I think? Main downside is that it’s really full-width so you’ll see it stick out on wider screens.

It’s not perfect, but it’s fast though

[Lilly (Lillian Louis)]

@Steve_John

• Tips for using per-category uploads or theme settings to set the background image cleanly.

I think the closest theme-component I’ve seen to what you are looking for is this one:

Discourse Category Headers theme component

This theme component provides a number of enhancements for the Discourse category header. The ‘standard’ Discourse category header is displayed at the top of each category page, above the navigation links and list of topics. It is normally only visible if a category logo image has been uploaded in the category settings. The header displays the logo and a short description of the category, taken from the first paragraph of the ‘About the… category’ topic. This theme component provides the foll…

You could have a look at that one to get some ideas, but it sounds like you may need to build a custom component. You could post in Marketplace if you are looking to hire some developers to help.

[chapoi (Charlie)]

Yes, that theme component is probably a better bet, hadn’t seen it before TIL