Discourse Welcome Modal

Theme component
1
:information_source: Summary A welcome modal to help new or returning community members with actionable ways to begin exploring/engaging in a forum
:eyeglasses: Preview Theme Creator (Requires being logged in)
:hammer_and_wrench: Repository GitHub - noahLovell/discourse-welcome-modal
:question: Install Guide How to install a theme or theme component
:open_book: New to Discourse Themes? Beginner’s guide to using Discourse Themes?

Install this theme component

:rocket: Why use this?

Many communities see high signup rates but struggle with “first-day churn.” This component reduces cognitive load by providing clear, actionable paths.

It supports segmentation, allowing you to serve different content to brand-new signups versus members returning after a hiatus.

:camera_flash: Screenshots

Desktop

Screenshot 2026-02-03 at 23.08.08
Screenshot 2026-02-03 at 23.08.081920×1033 158 KB

How it works

1. The Definitions

  • New Users: Users who registered on or after your feature_enabled_date.
  • Existing Users: Users who registered before your feature_enabled_date.
  • Engaged Users: Members who visit regularly. As long as they don’t stay away longer than the returning_user_inactivity_months, they stay Engaged.
  • Returning Users: Members who were previously Engaged but stayed away long enough to exceed the returning_user_inactivity_months threshold.

2. The Logic Flow

The component follows this priority list to ensure it doesn’t annoy your most active members:

  1. New Registration? They see the modal immediately (targeted with card_content marked as new_users or both).
  2. Grace Period (For Existing Users): If an “Existing User” visits during the grace_period_months window, the component silently marks them as seen. They won’t see the modal, as the logic assumes they are currently active and don’t need a welcome.
  3. The Inactivity Gap: Once a user is marked as having “seen” the modal (either silently or manually), the component tracks their visits locally. If they visit daily, they remain Engaged and never see it again. They will only be re-introduced to the modal (as a Returning User) if the gap between their visits exceeds your returning_user_inactivity_months setting.

3. Tailored Content

You can target specific cards to specific groups using the displayFor setting:

  • new_users: Perfect for “How to post” or “Introduce yourself.”
  • returning_users: Perfect for “Check out what’s changed while you were gone.”
  • both: Essential links like Guidelines or FAQ.

:gear: Settings

Setting Type Default Description
enabled bool false Global toggle for the component.
feature_enabled_date string "2026-02-06" The “Line in the Sand” for New vs Existing users (YYYY-MM-DD).
grace_period_months integer 3 Existing users visiting within this window are silently opted-out.
returning_user_inactivity_months integer 6 The “Inactivity Threshold.” Users see the modal again only if they stay away longer than this.
card_layout enum "grid" Display cards in a grid or list format.
card_content objects [] Define cards and set displayFor to new_users, returning_users, or both.

Testing your setup

Use these URL parameters to bypass the logic and preview your work:

  • ?show-welcome-modal=true&user-type=new - Previews the “New User” experience.
  • ?show-welcome-modal=true&user-type=returning - Previews the “Returning User” experience.

This is my first proper theme component :raised_hands: I’d love feedback on the new segmentation features or thoughts on what else could be improved! :smile:

20 Likes
2

Hi @noahl

What’s the easiest way to test this and see the tiles like in your demo images? Is there a certain set of settings that would allow admins to see the tiles before we make this available more broady in a PORD environment?

2 Likes
3

Hey @marksalter! You’re my first “feature requester” :raising_hands:

Just pushed an enable setting, along with a query param to force show the modal - ?show-welcome-modal=true

If you combine both of these, you’ll be able to test as an Admin before enabling for users :slight_smile:

e.g. set the enabled to off (it won’t display to anyone), and then use the query param to force view it.

6 Likes
4

Works like a charm! Thanks for taking a look.

3 Likes
5

Just a thought for your next round of development. Would be nice if we could stipulate which messages were shown to new users vs existing users who haven’t been active during the grace period.

So the new folks get welcome type messages (Go to the getting started material) while the existing folks get a what’s new type message (check out these new features / categories / things..).

4 Likes
6

This is really nice! Great work :clap:

What do you think about removing the footer? Since there are CTAs, along with the close button, Done feels a little unnecessary but curious to what you think?

7

Love this idea! It was something I had considered for the first pass, but I decided to keep the initial release simple.

Anyway, I’ve just pushed an update that implements this segmentation! There is a small change to the logic to distinguish between different user states so you can tailor the content without being intrusive.

How it works now:

1. The Definitions

  • New Users: Registered on or after your feature_enabled_date.
  • Existing Users: Registered before that date.
  • Engaged Users: Members visiting regularly (within your inactivity window).
  • Returning Users: Previously engaged members who stayed away long enough to exceed the inactivity threshold.

2. The Logic Flow To ensure we don’t annoy your most active members, the component follows a specific priority:

  • New Registration: They see the modal immediately (targeted with cards marked new_users or both).
  • Grace Period: If an ‘Existing User’ visits during your grace period, the component silently marks them as seen so they aren’t interrupted.
  • The Inactivity Gap: Once a user is marked as ‘seen’, the component tracks visits locally. If they visit daily, they stay Engaged and never see it again. They only see it (as a Returning User) if the gap between their visits exceeds your returning_user_inactivity_months setting (this is a new setting :slight_smile: )

3. Tailored Content You can now use the displayFor setting on each card:

  • new_users: Perfect for ‘How to post’ or ‘Introduce yourself.’
  • returning_users: Perfect for ‘Check out what’s changed while you were gone.’
  • both: Essential links like Guidelines or FAQ.

I’ve also added preview parameters so you can test these flows easily: ?show-welcome-modal=true&user-type=new or &user-type=returning.

Thanks again for the nudge!

3 Likes
8

@noahl That’s awesome!

I’ll try and have a look at this later today or Monday and let you know how things go.

1 Like