πŸ“‘ In this article

  1. Problem: filters in OpenCart and why standard modules break themes
  2. What is AI Filters v1.0.5 and why event-injected rendering
  3. Quick install in 5 minutes
  4. What you get out of the box
  5. Compatibility with popular OpenCart themes
  6. Advanced settings: GA4, URL-state, exclude-self
  7. Troubleshooting: 6 common issues
  8. FAQ

Standard OpenCart has no filters on the search page, and on category pages they reload the entire page. Third-party modules typically require twig template edits β€” meaning when you update the theme, you either redo everything or filters break. AI Filters v1.0.5 solves this with event-injected rendering: zero theme edits, AJAX mode, works on both categories and search pages.

Problem: filters in OpenCart and why standard modules break themes

OpenCart 3 and 4 ship with a weak filter mechanism out of the box:

  • On category pages β€” attribute filters reload the full page on every click. On 5k+ SKU catalogs this slows UX to unacceptable levels.
  • On the search page (/index.php?route=product/search) standard filters don't exist at all. A buyer found 247 products β€” can't narrow by brand or price.
  • OpenCart has no per-facet count β€” user doesn't know how many products will remain after a click until they click.

Third-party modules (especially popular ones in the OpenCart marketplace) typically modify category and search template files. Consequences:

⚠️
Classic trap of template-based filters: when you update the theme (or buy a new one) β€” filters either disappear or break the layout. The theme developer fixes the template, and your filter module expects the old one.

What is AI Filters v1.0.5 and why event-injected rendering

AI Filters is a faceted module shipped with AI Search v1.0.5. Works standalone (you can use it without AI search) or together. Key principle β€” event-injected: the module doesn't modify template files. Instead it subscribes to standard OpenCart events catalog/view/category/before and catalog/view/product/search/before, and inserts filter HTML into already-rendered output.

πŸ’‘
What it means in practice: you update the theme β€” filters keep working. You buy a new theme β€” install it and filters appear without any edits. No modifications to category.twig or search.twig needed.

Quick install in 5 minutes

  1. Sign up at ai-search.cc β€” Google login or email.
  2. Download aisearch.ocmod.zip from your dashboard β€” one archive for both AI Search and AI Filters.
  3. OpenCart admin: Extensions β†’ Installer β†’ Upload β†’ select zip β†’ Continue.
  4. Extensions β†’ Modifications β†’ Refresh (important β€” otherwise events won't activate).
  5. Extensions β†’ Extensions β†’ Modules β†’ find AI Filters β†’ Install β†’ Edit β†’ enable Status: Enabled β†’ Save.
  6. Go to frontend, open any category or search page. Filters appear on the left (or in your configured position).

What you get out of the box

⚑
AJAX mode without reloads
🎯
Per-facet counts (exclude-self)
πŸ”—
URL-state for sharing
πŸ“Š
GA4 / dataLayer events

AJAX mode: switch without reload

User clicks checkbox β€” filter panel and product list refresh without page reload. This is not SPA-overlay (like Klevu) β€” just XHR request to your own endpoint that returns new product ID list. URL changes via history.pushState(), so user can share a link with active filters.

Per-facet counts with exclude-self logic

If you have groups "Color", "Size", "Brand", and user already selected "Black", "M" β€” other checkboxes show how many products will remain after adding this filter. But within "Color" group numbers stay without considering "Black" β€” so user sees how many products exist in other colors with the same size/brand filters.

Native HTML5 dual-range slider for price

No third-party JS libraries. Works on mobile (touch). Debounced β€” XHR fires after 500ms of inactivity, not every pixel.

URL-state in CSV format

Example URL with active filters

/index.php?route=product/category&path=20&ai_f[manufacturer]=12,15&ai_f[price]=100-500&ai_f[color]=red,blue

Format ai_f[group]=v1,v2,v3 β€” human-readable, easy to debug, share-friendly.

GA4 / dataLayer events

Each filter application fires:

{ event: 'ai_filters_applied', filter_group: 'manufacturer', filter_value: '12', total_results: 47 }

Compatibility with popular OpenCart themes

Event-injected approach works with any theme that doesn't disable standard OpenCart events. Verified on:

  • Default OpenCart 3.x / 4.x β€” full compatibility
  • Journal 3 / Journal 4 β€” works without configuration
  • OctTheme β€” works, recommend disabling Oct's own filters to avoid conflict
  • Ronix β€” works
  • Shoppica β€” works

Advanced settings

1. Position: left column vs top

Module admin: Filter Position β†’ Left column / Top horizontal / Custom.

2. Active groups + sorting

Choose which groups to show: price, manufacturer, color, size, options, attributes, stock, rating. Drag-n-drop order.

3. Mobile sticky bottom button

On mobile, filter panel hides behind bottom button "Filters (3)" with active count badge.

4. Conditional rules

"Show 'Color' filter only if there are at least 3 different colors in active results."

5. Counts caching

Per-facet counts cached at Redis or file-cache level. Cache invalidates automatically on product changes.

Troubleshooting: 6 common issues

❓
Filters don't appear after install.
99% β€” forgot Extensions β†’ Modifications β†’ Refresh. Without it events don't activate. Refresh, clear Twig cache, retry.
❓
Filters appear but AJAX doesn't work (full reload).
Check jQuery is loaded. If your theme uses bundling without jQuery β€” enable AI Filters β†’ Settings β†’ Load jQuery in catalog.
❓
Counts show 0 for all filters.
Run AI Search reindex via Extensions β†’ Modules β†’ AI Search β†’ Edit β†’ Indexer β†’ Start Indexing.
❓
Conflict with theme's own filters.
Disable them in theme settings or in AI Filters select "Replace theme filters".
❓
Price slider breaks on mobile.
Check viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1">.
❓
URL doesn't preserve filter state after reload.
Theme overrides window.history. Contact [email protected].

FAQ

Is AI Filters a separate product or part of AI Search?

Shipped with AI Search v1.0.5 β€” one zip, one license. Can be used without AI search (disable AI Search, leave AI Filters Enabled).

Is it free?

On Free plan (up to 200 SKU) β€” yes. On paid tiers AI Filters is included without extra fees: Starter $12, Business $29, Pro $79, Enterprise $199.

Does it work on OpenCart 2.x?

No. Only OpenCart 3.0.x and 4.0.x. OC 2 has different event system.

What about multistore?

Works. Module settings can be configured per store via OpenCart's standard store-selector.

Can I configure different filter groups for search vs categories?

Yes. Admin has two separate tabs: Category Page Filters and Search Page Filters.