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

Go to Appearance > Widgets.
Find any of the five hashtag widgets in the available-widgets panel.
Drag it into your chosen sidebar, or click the widget and choose a sidebar from the dropdown.
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.

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)`.
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.

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>

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>

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>

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.

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 count — the most-used hashtag renders at up to 28 px; the least-used renders at 14 px. The size bucket is calculated in steps of 10% (CSS classes bpht-hashtag--size10 through bpht-hashtag--size100).

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

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), 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_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 );