Styling Top 10 Popular Posts

This guide explains how Top 10 loads its CSS and how to override it safely without modifying plugin files.

It applies to both the free and Pro versions. See Top 10 – Popular Posts for WordPress for the free plugin and Top 10 Pro for additional features.

What this covers

• How preset styles are enqueued
• How Custom CSS is injected
• Runtime CSS variables generated from plugin settings
• Stable selectors for targeted overrides
• Troubleshooting when styles do not apply

Prerequisites

• Top 10 is active
• Access to Top 10 → Settings → Styles
• Ability to clear all cache layers, including plugin, page, and CDN cache

How Top 10 loads CSS

Top 10 uses two styling layers:

1. A preset style CSS file
2. The Custom CSS field (optional)

When you select a style, Top 10 registers and enqueues a stylesheet using the handle: tptn-style-{style}.

The stylesheet path is resolved dynamically to account for:

• Minified versus non-minified files (SCRIPT_DEBUG)
• RTL stylesheets (is_rtl())
• Pro styles stored under includes/pro/frontend/css/ when the style name contains -pro

This ensures the correct file loads based on debug mode, language direction, and license state.

Built-in styles and CSS files

Style IDs map to stylesheet names as follows:

• no_style → No stylesheet enqueued
• text_only → text-only → includes/frontend/css/text-only(.min).css
• left_thumbs → left-thumbs → includes/frontend/css/left-thumbs(.min).css
• grid_thumbs (Pro) → grid-thumbs-pro → includes/pro/frontend/css/grid-thumbs-pro(.min).css

If it is an RTL site, the corresponding RTL stylesheet is enqueued.

Dynamic CSS variables generated by PHP

Top 10 injects inline CSS variables derived from settings such as thumb_width and thumb_height.

Left thumbnails

Injected on:

.tptn-left-thumbs

Variables:

• --tptn-thumb-width
• --tptn-thumb-height

These control thumbnail dimensions and image constraints in the left thumbnail layout.

Grid thumbnails (Pro)

Injected on:

.tptn-grid-thumbs

Variables:

• --tptn-grid-thumb-width
• --tptn-grid-thumb-height

These control the thumbnail dimensions in the grid layout.

The base Pro stylesheet also defines reusable variables, including:

• --tptn-grid-gap
• --tptn-grid-thumb-min-size
• --tptn-grid-card-bg
• --tptn-grid-card-border
• --tptn-grid-card-shadow
• --tptn-grid-card-shadow-hover
• --tptn-grid-card-muted
• --tptn-grid-card-radius

These can be overridden without modifying plugin files.

Output classes for targeted overrides

Top 10 outputs stable, predictable classes:

• Main wrapper: .tptn_posts or .tptn_posts_daily
• Context wrappers: .tptn_posts_widget, .tptn_posts_shortcode, .tptn_posts_block
• Style wrappers: .tptn-text-only, .tptn-left-thumbs, .tptn-grid-thumbs
• Link: .tptn_link
• Thumbnail: .tptn_thumb
• Content wrapper: .tptn_after_thumb
• Text and meta: .tptn_title, .tptn_date, .tptn_excerpt, .tptn_list_count

For dependable overrides, scope rules to both the wrapper and the active style class:

.tptn_posts.tptn-left-thumbs .tptn_title {
    line-height: 1.35;
}

How Custom CSS is enqueued

Custom CSS from the custom_css setting is printed in the page head as an inline <style> block.

This output is global and not restricted to specific contexts.

If CSS appears to be missing, the common causes are:

• Stale caching
• Selector mismatch
• Specificity conflicts

Style-specific notes

Text only

Applies a minimal wrapper rule (clear: both). It does not provide thumbnail styling.

If the thumbnail location is set to “Do not display thumbnails, only text”, Top 10 forces text-only behavior at runtime.

Left thumbnails

Uses a flex layout for each list item. Thumbnails include border and shadow styles with hover transitions.

Reduced-motion handling is implemented using prefers-reduced-motion.

Grid thumbnails (Pro)

Uses CSS Grid for the list layout. Container queries control responsive behavior.

Images use a fixed height with object-fit: cover for consistent card sizing.

Reduced-motion handling is included for hover transitions.

Practical override examples

.tptn_posts {
    margin-top: 1.5rem;
}

.tptn_posts.tptn-left-thumbs {
    --tptn-thumb-width: 180px;
    --tptn-thumb-height: 120px;
}

.tptn_posts.tptn-grid-thumbs {
    --tptn-grid-gap: 16px;
    --tptn-grid-thumb-min-size: 200px;
    --tptn-grid-card-radius: 10px;
}

.tptn_posts .tptn_list_count {
    opacity: 0.8;
}

Troubleshooting

Style does not apply

1. Confirm the style is saved in Top 10 → Settings → Styles
2. Confirm the output includes the expected wrapper class, for example .tptn-left-thumbs
3. Clear all caching layers
4. Check selector specificity before using !important

Grid thumbnails style is unavailable

1. Confirm Pro is active and licensed
2. Confirm the selected style is grid_thumbs
3. Confirm the rendered wrapper includes .tptn-grid-thumbs

Thumbnails unexpectedly disappear

1. Check the Thumbnail location setting
2. If set to text-only mode, Top 10 forces text-only behavior

Recommendation for maintainable styling

Start with a built-in style. Override CSS variables first. Use selector-level overrides only when variables are insufficient.

This keeps customizations small, stable across updates, and easier to troubleshoot.