Widgets & Shortcodes

Add hashtag clouds or lists to any sidebar using WordPress widgets, or embed them directly in pages and posts with shortcodes.

Widgets overview

The plugin registers five widgets. Four are always available once the plugin is active; the fifth requires bbPress.

Widget name (in the widget picker)	Class ID	Always available?
#Hashtags - Activity	BPHT_Hashtag_Widget	Yes
#Hashtags - Posts	BPHT_Hashtag_Post_Widget	Yes
#Hashtags - Pages	BPHT_Hashtag_Page_Widget	Yes
#Hashtags - Most Followed	BPHT_Followed_Hashtag_Widget	Yes, unless you disable the Follow Hashtags feature in General Settings
#Hashtags - Forums	BPHT_Bbpress_Hashtag_Widget	Only when bbPress is active

Adding a widget

1. Go to Appearance > Widgets.
2. Find any of the five hashtag widgets in the available-widgets panel.
3. Drag it into your chosen sidebar, or click the widget and choose a sidebar from the dropdown.
4. Fill in the options (described below) and click Save.

On sites using the block-based widget editor (WordPress 5.8+), search for “Legacy Widget” in the block inserter, then pick the hashtag widget you want from the list inside that block.

Widget settings

All five widgets share the same set of options. The table below describes each field and where it appears.

Field	Applies to	What it controls
Title	All widgets	The heading displayed above the hashtag list. Leave blank to hide the heading.
Limit	All widgets	How many hashtags to pull from the database and display. Range: 1-50. Default: 12.
Display style	All widgets	Cloud - hashtags flow inline at varying sizes scaled by count. List - hashtags stack vertically at a uniform size.
Sort by	All widgets	Sorted by name - alphabetical. Sorted by size (or “by followers” on the Most Followed widget) - ordered by use count. Sorted by date - most recently active first. Random - reshuffled on every page load.
Sort order	All widgets	Up arrow (ascending) or down arrow (descending). Has no effect when Sort by is set to Random.
Show count	All widgets	Check to append the usage count (or follower count on the Most Followed widget) after each hashtag label, e.g. #photography (42).
Time range	Activity widget only	Show what is trending in a recent window instead of all-time. Options: All time (default), Last 24 hours, Last 7 days, Last 30 days. See “Trending time range” below.
Enable cache	Activity widget only	Cache the rendered widget HTML as a WordPress transient to reduce database queries.
Cache time	Activity widget only	How long (in seconds) to keep the cached output. Default: 3600 (one hour). The cache is cleared automatically when you save the widget settings and whenever a new hashtag is posted anywhere on the site.

Activity widget — what it displays

Shows hashtags drawn from BuddyPress activity updates and activity comments. The source data type stored in the database is activity (legacy records may carry buddypress; both are included in the query).

Each hashtag links to:

/activity/?activity_search=%23<hashtag>

Trending time range (3.8.0+)

By default the Activity widget ranks hashtags by their all-time use count. Set Time range to a recent window (Last 24 hours, Last 7 days, or Last 30 days) to instead rank by how often each hashtag was used within that window — so the widget reflects what your community is talking about right now, not what was popular a year ago.

• Trending popularity is measured from real activity in the chosen window (counted from the hashtag-to-content records the plugin stores), so the order updates as the conversation moves.
• In Cloud display style, each tag’s size scales by its popularity within the current results, so the busiest hashtags in the window stand out at a glance.
• Empty-window fallback: if the chosen window has no recent activity, the widget automatically falls back to all-time popular hashtags and shows a short note (“No recent activity in this period - showing all-time popular hashtags.”) instead of an empty widget. Developers can hide or replace that note with the bpht_widget_fallback_notice filter (see Developer reference).

Posts widget — what it displays

Shows hashtags drawn from WordPress blog posts (post type post, stored as post in the database). Each hashtag links to the site search:

/?s=%23<hashtag>

Pages widget — what it displays

Shows hashtags drawn from WordPress pages (post type page, stored as page in the database). Each hashtag links to the site search:

/?s=%23<hashtag>

Most Followed widget — what it displays

Shows hashtags that community members have followed the most. The underlying data type is profile. The count shown (when “Show count” is on) is the number of followers, not the number of posts. This widget only appears in the widget picker when the Follow Hashtags feature is enabled. To check or change that setting: WB Plugins > BuddyPress Hashtag > General, then look for the Enable Hashtag Following toggle.

Forums widget — what it displays

Shows hashtags drawn from bbPress forum topics and replies (stored as bbpress in the database). This widget is registered only when bbPress is active on the site. If bbPress is deactivated after you have placed this widget in a sidebar, WordPress will show the widget area as “inactive” and the widget will move to the Inactive Widgets section automatically.

Each hashtag links to the bbPress search, using the site’s configured search slug:

/<forum-root>/<search-slug>/%23<hashtag>

Empty state

When a widget has no hashtags to display (the database table does not exist yet, or no hashtags match the length constraints in General Settings), the widget outputs the text “No hashtags” in muted style. The widget area wrapper is still rendered, so any widget title you set will appear above the message.

---

Shortcodes

Use shortcodes to embed a hashtag cloud or list inside a post, page, or text widget without needing a sidebar.

[bpht_bp_hashtags]

Displays hashtags from BuddyPress activity. This shortcode is always available when the plugin is active.

Parameters:

Parameter	Accepted values	Default	Description
displaystyle	cloud / list	cloud	Cloud flows inline; list stacks vertically.
sortby	name / size	name	Sort alphabetically or by use count.
sortorder	asc / desc	asc	Direction of the sort.
limit	any whole number	12	How many hashtags to display.

Examples:

[bpht_bp_hashtags]

[bpht_bp_hashtags displaystyle="cloud" sortby="name" sortorder="asc" limit="12"]

[bpht_bp_hashtags displaystyle="list" sortby="size" sortorder="desc" limit="20"]

Each hashtag in the output links to the BuddyPress activity search:

/activity/?activity_search=%23<hashtag>

When there are no hashtags to show, the shortcode outputs “No hashtags” in a muted span.

[bpht_bbpress_hashtags]

Displays hashtags from bbPress forums. This shortcode is only registered when bbPress is active. If bbPress is not installed, the shortcode tag will remain in the page output as plain text.

Parameters: Same as [bpht_bp_hashtags].

Parameter	Accepted values	Default	Description
displaystyle	cloud / list	cloud	Display format.
sortby	name / size	name	Sort method.
sortorder	asc / desc	asc	Sort direction.
limit	any whole number	12	Number of hashtags to show.

Examples:

[bpht_bbpress_hashtags]

[bpht_bbpress_hashtags displaystyle="list" sortby="name" sortorder="asc" limit="15"]

Each hashtag links to the bbPress search, using the forum root and search slugs configured in your bbPress settings.

Where you can use shortcodes

• Any post or page in the block editor (use the Shortcode block) or the classic editor
• Text widgets in sidebars
• Page builder text modules (Elementor, Beaver Builder, Divi, and similar)
• Custom page templates via do_shortcode()

---

Display style reference

Cloud

Hashtags render inline. Size scales with popularity relative to the current result set — the most-used hashtag in the list renders largest, the least-used smallest, in steps of 10% (CSS classes bpht-hashtag--size10 through bpht-hashtag--size100). Because the scale is relative, the cloud stays readable whether your busiest tag has 12 uses or 12,000 (before 3.8.0 the scale was fixed, so any count above ~12 saturated to a single size).

CSS classes applied in cloud mode:

• Wrapper: bpht-hashtags-wrapper bpht-hashtags-wrapper-cloud
• Each item: bpht-hashtag--box bpht-hashtag--size<n> where <n> is 10–100

List

Hashtags stack vertically at a uniform size. The size classes are not applied; display:block or similar layout from the theme governs spacing.

CSS classes applied in list mode:

• Wrapper: bpht-hashtags-wrapper bpht-hashtags-wrapper-list
• Each item: no size class (empty data-size attribute)

---

CSS customization

The markup uses these stable hooks you can target with custom CSS:

/* All hashtag links */
a.hashtag { }

/* Widget/shortcode outer container */
.bpht-widget--hashtags { }

/* Cloud layout wrapper */
.bpht-hashtags-wrapper-cloud { }

/* List layout wrapper */
.bpht-hashtags-wrapper-list { }

/* Size tiers (cloud mode only, 10–100 in steps of 10) */
.bpht-hashtag--size10  { /* smallest */ }
.bpht-hashtag--size100 { /* largest  */ }

---

Troubleshooting

Widget not showing up in Appearance > Widgets

• Confirm the plugin is active (Plugins > Installed Plugins).
• For the Forums widget: confirm bbPress is active.
• For the Most Followed widget: go to WB Plugins > BuddyPress Hashtag > General and make sure Follow Hashtags is enabled.

Widget shows “No hashtags”

• Create some content that contains hashtags (activity posts, blog posts, forum topics, or pages depending on the widget type).
• Check that your hashtag length settings allow the hashtags you have created (WB Plugins > BuddyPress Hashtag > General > Min/Max length).
• Clear any full-page or object caching (for example, WP Rocket or W3 Total Cache).
• If the Activity widget has caching enabled, reduce the cache time or uncheck “Enable cache” temporarily.

Shortcode outputs plain text like [bpht_bbpress_hashtags]

• bbPress is not active. Activate bbPress, then reload the page.

Sorting by date not working as expected

• “Sorted by date” orders by ht_last_count (the timestamp of the most recent activity that contained the hashtag), with overall count as the tiebreaker. Hashtags that have never been used since the last plugin reset will fall to the bottom.

---

Developer reference

Widget-instance filters

Each widget passes its settings array through a filter before rendering. Use these to programmatically alter any widget instance — for example, to force a specific limit or swap the display style based on a condition.

bpht_bp_hashtag_widget_instance

Runs on the Activity widget instance before output.

add_filter( 'bpht_bp_hashtag_widget_instance', function( $instance ) {
    // Force cloud display on mobile
    if ( wp_is_mobile() ) {
        $instance['displaystyle'] = 0; // 0 = cloud
        $instance['limit']        = 8;
    }
    return $instance;
} );

$instance keys: title, limit, sortby (int: 0=name, 1=size, 2=random, 3=date), sortorder (int: 0=asc, 1=desc), displaystyle (int: 0=cloud, 1=list), count (int: 0 or 1), date_range (string: all/24h/7d/30d, Activity widget, 3.8.0+), enable_cache (int), cache_time (int).

bpht_bbpress_hashtag_widget_instance

Runs on the Forums widget instance before output. Same $instance key structure as the Activity widget (minus enable_cache and cache_time).

bpht_followed_hashtag_widget_instance

Runs on the Most Followed widget instance before output. Same $instance key structure.

BPHT_Hashtag_Post_Widget_instance

Runs on the Posts widget instance before output. Same $instance key structure.

BPHT_Hashtag_Page_Widget_instance

Runs on the Pages widget instance before output. Same $instance key structure.

bpht_widget_fallback_notice

Runs on the Activity widget (3.8.0+) when a trending Time range has no in-window activity and the widget falls back to all-time hashtags. Return false to suppress the “showing all-time popular hashtags” note, or use it to conditionally hide it.

// Never show the fallback notice
add_filter( 'bpht_widget_fallback_notice', '__return_false' );

Parameters:

• $show (bool) - Whether to print the fallback note. Default true.
• $instance (array) - The current widget instance settings.

bpht_bp_hashtag_widget_form

Runs before the widget settings form is rendered in the admin. Use this to inject additional HTML into the form.

add_filter( 'bpht_bp_hashtag_widget_form', function( $settings ) {
    $settings['html'] .= '<p><strong>Custom note:</strong> Visible to admins only.</p>';
    return $settings;
} );

$settings keys: html (string to prepend to the form), that (the widget instance), instance (current saved values).

Query filters

Both widgets and shortcodes fire wbcom_hashtag_widget_query before executing the database query, and wbcom_hashtag_widget_array_hashtags after the results are sorted.

wbcom_hashtag_widget_query

Modify the SQL before it runs. Return a different query string to override what gets fetched.

add_filter( 'wbcom_hashtag_widget_query', function( $sql, $type, $limit ) {
    if ( 'activity' === $type ) {
        // Only show hashtags used at least 3 times
        $sql = str_replace( 'ORDER BY', 'AND ht_count >= 3 ORDER BY', $sql );
    }
    return $sql;
}, 10, 3 );

Parameters:

• $sql (string) - The prepared SQL query string.
• $type (string) - The hashtag type: activity, bbpress, post, page, profile, or buddypress.
• $limit (int) - The limit value from widget or shortcode settings.

wbcom_hashtag_widget_array_hashtags

Modify the sorted hashtag array immediately before it is rendered. Each array item is an associative array with ht_count, ht_last_count, and ht_type keys.

add_filter( 'wbcom_hashtag_widget_array_hashtags', function( $hashtags, $type, $limit ) {
    // Remove hashtags shorter than 4 characters for the posts widget
    if ( 'post' === $type ) {
        $hashtags = array_filter( $hashtags, function( $data, $name ) {
            return mb_strlen( $name ) >= 4;
        }, ARRAY_FILTER_USE_BOTH );
    }
    return $hashtags;
}, 10, 3 );

Parameters:

• $hashtags (array) - Associative array keyed by hashtag name.
• $type (string) - The hashtag type (same values as wbcom_hashtag_widget_query).
• $limit (int) - The original limit value.