# Discourse Welcome Modal
**URL:** https://meta.discourse.org/t/discourse-welcome-modal/395095
**Category:** Theme component
**Created:** [February 3, 2026, 11:48pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095 "2026-02-03T23:48:20Z")
**Posts on this page:** 8
**Page:** 1
### Author:  [@noahl](https://meta.discourse.org/u/noahl)
#### Post date: [February 3, 2026, 11:48pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/1 "2026-02-03T23:48:20Z")
| | | |
| --- | --- | --- |
| ℹ | **Summary** | A welcome modal to help new or returning community members with actionable ways to begin exploring/engaging in a forum |
| 👓 | **Preview** | [Theme Creator](https://discourse.theme-creator.io/?preview_theme_id=10412) (Requires being logged in) |
| 🛠 | **Repository** | [GitHub - noahLovell/discourse-welcome-modal · GitHub](https://github.com/noahLovell/discourse-welcome-modal) |
| ❓ | **Install Guide** | [How to install a theme or theme component](https://meta.discourse.org/t/how-do-i-install-a-theme-or-theme-component/63682) |
| 📖 | **New to Discourse Themes?** | [Beginner’s guide to using Discourse Themes?](https://meta.discourse.org/t/beginners-guide-to-using-discourse-themes/91966) |
Install this theme component
## 🚀 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.
* * *
## 📸 Screenshots
### Desktop
* * *
## 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.
* * *
## ⚙ 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 🙌 I’d love feedback on the new segmentation features or thoughts on what else could be improved! 😄_
---
### Author:  [@marksalter](https://meta.discourse.org/u/marksalter)
#### Post date: [February 5, 2026, 5:01pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/2 "2026-02-05T17:01:45Z")
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?
---
### Author:  [@noahl](https://meta.discourse.org/u/noahl)
#### Post date: [February 5, 2026, 5:41pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/3 "2026-02-05T17:41:47Z")
Hey @marksalter! You’re my first “feature requester” 🙌
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 🙂
e.g. set the enabled to off (it won’t display to anyone), and then use the query param to force view it.
---
### Author:  [@marksalter](https://meta.discourse.org/u/marksalter)
#### Post date: [February 5, 2026, 5:44pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/4 "2026-02-05T17:44:26Z")
Works like a charm! Thanks for taking a look.
---
### Author:  [@marksalter](https://meta.discourse.org/u/marksalter)
#### Post date: [February 5, 2026, 6:00pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/5 "2026-02-05T18:00:40Z")
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..).
---
### Author:  [@jordan.vidrine](https://meta.discourse.org/u/jordan.vidrine)
#### Post date: [February 6, 2026, 10:51am UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/6 "2026-02-06T10:51:38Z")
This is really nice! Great work 👏
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?
>
---
### Author:  [@noahl](https://meta.discourse.org/u/noahl)
#### Post date: [February 6, 2026, 1:43pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/7 "2026-02-06T13:43:32Z")
> [@marksalter](#):
>
> 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
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 🙂 )
**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!
---
### Author:  [@marksalter](https://meta.discourse.org/u/marksalter)
#### Post date: [February 6, 2026, 3:00pm UTC](https://meta.discourse.org/t/discourse-welcome-modal/395095/8 "2026-02-06T15:00:13Z")
@noahl That’s awesome!
I’ll try and have a look at this later today or Monday and let you know how things go.