# Topic Hover Cards
**URL:** https://meta.discourse.org/t/topic-hover-cards/400025
**Category:** Theme component
**Created:** [April 6, 2026, 1:48pm UTC](https://meta.discourse.org/t/topic-hover-cards/400025 "2026-04-06T13:48:20Z")
**Posts on this page:** 2
**Page:** 1
### Author:  [@denvergeeks](https://meta.discourse.org/u/denvergeeks)
#### Post date: [April 6, 2026, 1:48pm UTC](https://meta.discourse.org/t/topic-hover-cards/400025/1 "2026-04-06T13:48:21Z")
| | | |
| --- | --- | --- |
| ℹ | **Summary** | Provides tooltip-style popups when mousing over (or tapping on mobile) internal topic links to show a quick preview of the linked topic’s content. |
| 👓 | **Preview** | [Github Readme](https://github.com/denvergeeks/discourse-topic-hover-cards/blob/main/README.md) |
| 🛠 | **Repository** | [https://github.com/denvergeeks/discourse-topic-hover-cards](https://github.com/denvergeeks/discourse-topic-hover-cards) |
| ❓ | **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
Rich hover preview cards for **internal Topic links** across topics, replies, topic lists, the categories homepages, doc categories, kanban boards, and suggested topics. For Desktop and/or Mobile. Sitewide and highly configurable.
## Features
- Can be activated sitewide for all internal topic links, or just those appearing in one or more areas including:
- Topic body (original post)
- Replies
- Standard topic lists (`/latest`, `/top`, `/tags`, category topic lists, etc.)
- Categories homepage topic lists (Categories + Latest, Categories-only, and related layouts)
- Doc Categories
- Kanban Board
- Suggested Topics
- Responsive layout:
- Desktop card with configurable density and thumbnail placement
- Mobile bottom-sheet preview with tap-to-open
- Configurable content can include:
- Thumbnail image
- Topic Title
- Excerpt
- Category
- Tags
- Original poster (username and avatar)
- Publish Date
- Last Activity Date
- Number of Views
- Number of Replies
- Number of Likes
- Per-user opt-out using a custom user field
- Admin-only debug mode for safe troubleshooting
> **Click to see all of the settings included...**
>
> ### Layout & timing
>
> - **card\_width**
> Any CSS width value (for desktop), e.g. `32rem`, `420px`, `40vw`, `clamp(20rem, 40vw, 36rem)`.
>
> - **card\_max\_height**
> Any CSS max-height value, e.g. `10rem`, `480px`, `50vh`, `min(60vh, 32rem)`.
>
> - **card\_delay\_ms**
> Delay before showing the hover card, in milliseconds (default: `300`).
>
> - **enable\_on\_mobile**
> When enabled, tap on a supported internal topic link shows a mobile preview sheet fixed to the bottom of the screen.
>
> - **mobile\_width\_percent**
> Width of the mobile bottom-sheet preview as a percentage of viewport width (default: `100`).
>
> - **mobile\_thumbnail\_height**
> Thumbnail height in pixels for the mobile preview.
>
> ### Density
>
> - **density**
> Desktop density: `default`, `cozy`, or `compact`.
>
> - **density\_mobile**
> Mobile density: `default`, `cozy`, or `compact`.
>
> These are akin to the Discourse “Density” patterns which adjust padding and line heights and font size.
>
> ### Thumbnail & placement
>
> - **show\_thumbnail** / **show\_thumbnail\_mobile**
> Show/hide the topic image (if any) on desktop and mobile.
>
> - **thumbnail\_placement**
> How the thumbnail is positioned on desktop:
>
> - **image\_size\_percent**
> Controls thumbnail size as a percentage of the rendered hover card size.
>
> ### Fields per viewport
>
> For each block below, you have both desktop and mobile toggles:
>
> - **show\_category** / **show\_category\_mobile**
>
> - **show\_tags** / **show\_tags\_mobile**
>
> - **show\_title** / **show\_title\_mobile**
>
> - **show\_excerpt** / **show\_excerpt\_mobile**
>
> - **excerpt\_length** / **excerpt\_length\_mobile**
> Number of lines for the excerpt (uses CSS line-clamp).
>
> - **show\_op** / **show\_op\_mobile**
> Shows original poster avatar + username.
>
> - **show\_publish\_date** / **show\_publish\_date\_mobile**
>
> - **show\_views** / **show\_views\_mobile**
>
> - **show\_reply\_count** / **show\_reply\_count\_mobile**
>
> - **show\_likes** / **show\_likes\_mobile**
>
> - **show\_activity** / **show\_activity\_mobile**
>
> ### Where hover cards appear
>
> - **enable\_on\_topics**
> Topic links in the original post.
>
> - **enable\_on\_replies**
> Topic links in replies.
>
> - **enable\_on\_topic\_lists**
> Topic links in standard topic lists, e.g. `/latest`, `/top`, category topic lists.
>
> - **enable\_on\_category\_homepage\_topic\_lists**
> Topic links in the “latest topics” or equivalent lists on the **categories homepage** :
>
> - **enable\_on\_doc\_categories**
> Topic links in **Doc Categories** views (when applicable).
>
> - **enable\_on\_kanban\_boards**
> Topic links rendered in Kanban-style board layouts (when applicable).
>
> - **enable\_on\_suggested\_topic\_links**
> Links in the “Suggested topics” section.
>
> * * *
>
> ## Per-user opt-out
>
> You can let individual users disable hover cards using a **custom user field**. This uses the standard theme-settings mechanism and current-user data access described in the developer guides.
>
> - **user\_preference\_field\_name**
> The key used to detect opt-out on the current user. This can be:
> - a direct custom field key, e.g. `disable_topic_hover_cards`
> - a numeric ID, e.g. `1`
> - a `user_field_X` key, e.g. `user_field_1`
>
> ### How matching works
>
> 1. The component first checks the current user’s `custom_fields` and `user_fields` for:
> - the configured `user_preference_field_name`
> - the same value converted between `1` and `user_field_1` when appropriate
>
> 2. If no match is found and the current user is staff (admin/moderator) and
> **resolve\_user\_field\_id\_for\_admins** is enabled, the component calls:
> - `/admin/config/user-fields.json`
> to map the configured value (field name or `user_field_X`) to its numeric ID.
>
> 3. With the numeric ID, it checks:
> - `user_fields[id]`
> - `user_fields['user_field_' + id]`
> - `custom_fields[id]`
> - `custom_fields['user_field_' + id]`
>
> Any truthy value in those positions (e.g. `1`, `true`, `yes`, `on`, `checked`) disables hover cards for that user.
>
> ### Settings for this behavior
>
> - **resolve\_user\_field\_id\_for\_admins**
> When enabled (recommended), admins can configure the field either by name or `user_field_X`, and the component will resolve and match the numeric ID automatically.
>
> - **debug\_mode**
> When enabled, logs detailed detection information to the browser console for staff, including:
>
> * * *
>
> ## Debugging
>
> If hover cards don’t appear where you expect, use the built-in debug mode:
>
> 1. Enable **debug\_mode** in this component’s settings.
> 2. Open the browser developer console.
> 3. Hover or tap a relevant topic link.
>
> You will see messages similar to:
>
> - `Hover cards initialized` – confirms initialization and the enabled locations.
> - `Resolved admin user-field mapping` – confirms mapping of your configured user field name / key to a numeric ID (for staff).
> - `No disable field match found anywhere` – confirms hover cards are not being suppressed for the current user.
>
> To debug **where** the card should appear, check that:
>
> - your target link is an internal topic link (`/t/...`) that `topicIdFromHref()` can parse
> - the relevant location flag is enabled:
> - `enable_on_topics`
> - `enable_on_replies`
> - `enable_on_topic_lists`
> - `enable_on_category_homepage_topic_lists`
> - `enable_on_doc_categories`
> - `enable_on_kanban_boards`
> - `enable_on_suggested_topic_links`
* * *
**Planned Settings and Features Yet To Add:**
- Excluded Tags
- Included Tags
- Excluded Classes
- Included Classes
- Exclude OneBoxes and others by default
- Suggestions??
---
### Author:  [@chapoi](https://meta.discourse.org/u/chapoi)
#### Post date: [April 6, 2026, 2:18pm UTC](https://meta.discourse.org/t/topic-hover-cards/400025/2 "2026-04-06T14:18:19Z")
Could you add a working preview link or some screenshots to show what this looks like?