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

Product Support

AI-generated summary

Steve_John is seeking help to recreate a per-category hero banner with a unique background image and overlay text for each category, aiming for a smooth load and responsive design without layout shifts. They tried custom JavaScript but faced issues with image resizing and layout shifts. chapoi suggested using the built-in category background image feature, adjusting CSS for the desired layout, noting it may stick out on wider screens. Lilly recommended exploring the Discourse Category Headers theme component for inspiration or hiring developers via the Marketplace if a custom solution is needed. chapoi agreed that the theme component is a better approach.

1

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

image
image1147×386 40.9 KB

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!

2

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:

CleanShot 2025-08-13 at 20.27.46@2x
CleanShot 2025-08-13 at 20.27.46@2x1920×1174 106 KB

If you just add a category background in the category settings

CleanShot 2025-08-13 at 20.29.46@2x
CleanShot 2025-08-13 at 20.29.46@2x1018×354 61.5 KB

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 :wink:

3

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

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.

4

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