FuseCommerce - Instant Product Search (Pro)

Version 1.0.0

Introduction

Support: SakuraLeaf

Product: FuseCommerce Instant Product Search for WooCommerce

Note! This documentation applies to both the free and pro plugin versions.

This documentation will help you install, configure, and customize the FuseCommerce Pro plugin. Please read through the documentation carefully to understand how this plugin works and how to get the most out of its features.

FuseCommerce transforms your WooCommerce store with instant, client-side product search powered by fuzzy matching algorithms. Your customers will enjoy lightning-fast search results as they type, with zero server delays.

FuseCommerce Pro is optimized for large catalogs and performs smoothly on stores with up to 10,000 products, delivering instant client-side search results without slowing down your site.

Key Benefits

Requirements

In order to work properly, the plugin requires the following:

  1. WordPress 6.4 or higher
  2. PHP 8.2 or higher
  3. WooCommerce (active and configured)

Installation

Follow these steps to install and activate the FuseCommerce Pro plugin:

  1. Deactivate the free version: If you have the free version of FuseCommerce installed, deactivate it first
  2. Log in to WordPress Admin: Navigate to Plugins > Add New > Upload Plugin
  3. Upload the ZIP file: Click "Choose File" and select the fusecommerce-pro.zip file
  4. Install the plugin: Click "Install Now" and wait for the installation to complete
  5. Activate the plugin: Click the "Activate" button
  6. Navigate to settings: Go to Admin > FuseCommerce to configure the plugin
  7. Start indexing: Click "Start Indexing" to create your product search index (see Product Indexing section)

Note! After activation, you must index your products before the search functionality will work. See the Product Indexing section for details.

Main Settings

Once you have installed and activated the plugin, navigate to Admin > FuseCommerce to access the settings page.

The settings page is organized into four main tabs:

  1. Indexing: Manage product indexing, start/resume/reset the index, and monitor progress
  2. Filters: Configure which filters appear on the frontend and their display order
  3. Shortcodes: View shortcode documentation and available parameters
  4. Settings: Configure plugin options like quick view, caching, and currency settings
FuseCommerce main settings page with four tabs

Product Indexing

Product indexing is the process of creating optimized JSON files that contain all your WooCommerce product data. This index is what makes client-side search possible.

Understanding the Indexing Process

FuseCommerce uses a two-phase indexing process designed to handle large stores:

  1. Phase 1: Taxonomies - Indexes categories, product attributes, and tags with their hierarchical relationships
  2. Phase 2: Products - Processes products in batches (30 products per batch by default) to prevent memory issues and timeouts

The indexing system includes intelligent time management that uses only 70% of your PHP max_execution_time, ensuring the process can be resumed if needed.

Starting Initial Indexing

To index your products for the first time:

  1. Navigate to Admin > FuseCommerce > Indexing tab
  2. Click the "Start Indexing" button
  3. Monitor the progress bar as products are indexed
  4. Wait for the completion message

Note! For large catalogs (~1000 products), indexing may take several minutes. The process runs in the background and resumes itself when it reaches max exec time.

Indexing tab before starting the indexing process
Indexing in progress with progress bar showing percentage

Index Files Generated

The indexing process creates the following JSON files in your WordPress uploads directory:

Storage Location: wp-content/uploads/fusecommerce/

Generated files:

Indexing completed successfully with file size information

Filter Configuration

The Filters tab allows you to control which filters appear in your frontend search interface and in what order.

Available Filter Types

FuseCommerce supports the following filter types:

Managing Filters

Navigate to Admin > FuseCommerce > Filters tab to configure your filters:

  1. Drag-and-drop to reorder: Click and drag filters to change their display order on the frontend
  2. Toggle visibility: Use checkboxes to show or hide specific filters
  3. Select attributes: Choose which product attributes should be available for filtering
  4. Refresh from index: Click "Refresh" to update filter options based on your latest product data

Category Hierarchy

Category filters automatically maintain parent/child relationships. When a parent category is selected, child categories are displayed for further refinement. Each category shows the number of products it contains.

Filters configuration interface with drag-and-drop ordering

Tip! Limit the number of visible filters to avoid overwhelming users. Focus on the most relevant filters for your product catalog.

Shortcode Usage & Configuration

The FuseCommerce search interface is added to your pages using simple shortcodes.

Main shortcode [fusecommerce]

Add the search interface to any page, post, or widget area:

[fusecommerce]

Available Attributes

Customize the search behavior by adding parameters to the shortcode. Here's an example with all available parameters:

[fusecommerce
  fuse_threshold="0.3"
  fuse_name_weight="2"
  fuse_short_description_weight="1"
  initial_products_load_no="12"
  load_more_products_no="12"
  free_search_debounce_delay="1000"
  tag_limit="10"
  category_limit="5"
]

Parameter Descriptions

fuse_threshold (0.0-1.0, default: 0.3) - Controls search sensitivity. Lower values = stricter matching, higher values = more lenient. Example: 0.2 for exact matches, 0.5 for loose matching
fuse_name_weight (number, default: 2) - Priority weight for product names in search results. Higher values make product names more important in search ranking
fuse_short_description_weight (number, default: 1) - Priority weight for product descriptions in search results. Increase to give more importance to description matches
initial_products_load_no (number, default: 12) - Number of products to display on initial page load before any filtering
load_more_products_no (number, default: 12) - Number of additional products to load when the "Load More" button is clicked
free_search_debounce_delay (milliseconds, default: 1000) - Delay before search triggers after user stops typing. Reduces processing on each keystroke
tag_limit (number, default: 10) - Maximum number of tags to display in the tag filter
category_limit (number, default: 5) - Maximum number of top-level categories to display initially

Usage Examples

Basic Shop Page

[fusecommerce initial_products_load_no="24"]

Shows 24 products initially, perfect for a main shop page.

Strict Matching

[fusecommerce fuse_threshold="0.2"]

Requires closer matches, ideal for technical products with specific names.

Mobile-Optimized

[fusecommerce initial_products_load_no="8" load_more_products_no="8"]

Loads fewer products at a time for better mobile performance.

Fast Search

[fusecommerce free_search_debounce_delay="300"]

Triggers search faster for a more responsive feel (good for small catalogs).

Cart icon shortcode [fusecommerce_cart_icon]

The [fusecommerce_cart_icon] shortcode displays the cart icon, which listens to cart updates. You can also place it in the top menu by going to Appearance > Menu > Custom Link and pasting the shortcode as a label.

Shortcodes tab displaying all available parameters and examples

Note! You can use multiple instances of the shortcode on different pages with different parameters to customize the search experience for different contexts.

Frontend Search Interface

The FuseCommerce frontend interface provides a powerful, user-friendly search experience for your customers.

Search Bar

The free text search bar features:

Filter Panel

Multiple filters can be applied simultaneously:

Frontend search interface desktop view

Product Display

Products are displayed in a responsive grid layout featuring:

Pagination

The search interface uses load-more pagination:

Mobile Responsive Design

The interface automatically adapts to mobile devices:

Frontend search with active filters showing filtered product results

Tip! All searches and filtering happen instantly in the browser without any server requests, providing a fast, smooth experience for your customers.

Quick View Feature

The Quick View feature allows customers to preview product details in a modal popup without leaving the search page.

Enabling Quick View

To enable the Quick View feature:

  1. Navigate to Admin > FuseCommerce > Settings tab
  2. Find the "Quick View" option
  3. Check the box to enable Quick View
  4. Save your settings

Using Quick View

When Quick View is enabled, each product in the search results displays a "Quick View" button. Clicking this button opens a modal that displays:

Variable Products

For products with variations (different sizes, colors, etc.), the Quick View modal provides:

Product grid showing search results with images and prices

Note! Quick View adds to cart via AJAX, keeping customers on the search page and maintaining their filters and search state.

Plugin Settings

Navigate to Admin > FuseCommerce > Settings tab to configure general plugin options.

Available Options

Cache Settings

Control client-side caching of product index:

Tip! Client-side caching significantly improves load times for returning visitors, especially with large product catalogs.

Quick View

Currency Settings

Customize how prices are displayed:

Display Options

Plugin settings tab displaying configuration options

Performance & Optimization

FuseCommerce is designed for exceptional performance, even with large product catalogs.

How Client-Side Search Works

Understanding the technology behind FuseCommerce:

  1. Index loaded once: When a page with the shortcode loads, the product index (JSON file) is fetched from your server
  2. Browser-side processing: The Fuse.js library performs all search and filtering operations in the visitor's browser
  3. Zero server requests: After the initial index load, no additional server requests are needed for search or filtering
  4. Fuzzy matching algorithm: Fuse.js uses sophisticated algorithms to find relevant matches even with typos

Index File Caching

Multiple layers of caching ensure optimal performance:

Large Catalog Handling

FuseCommerce can handle stores with thousands of products:

Best Practices for Optimal Performance

Note! Client-side search means your server resources are freed up for other tasks. Even during high traffic, search performance remains consistent because processing happens on the client side.

Automatic Change Detection

FuseCommerce automatically tracks changes to your products and can trigger reindexing as needed.

Product Change Tracking

The plugin hooks into WooCommerce product save events to detect:

Changes are stored and tracked until the next indexing operation processes them.

Auto-Reindexing

Set up automatic reindexing to keep your search index current:

  1. Navigate to Admin > FuseCommerce > Settings tab
  2. Find the "Auto-Reindex" section
  3. Enable automatic reindexing
  4. Choose a schedule frequency

Manual Reindexing

You can always trigger manual reindexing:

Developer Resources

FuseCommerce provides hooks and filters for developers to customize and extend the plugin's functionality.

Find out more about how to extend the plugin

Available PHP filters

Available JS filters

REST API Endpoints

FuseCommerce registers REST API endpoints for programmatic access:

GET /wp-json/fusecommerce/v1/index - Get current filter configuration

External Resources

Note! Always test customizations on a staging site before deploying to production. Custom code should follow WordPress coding standards and be properly escaped for security.

Changelog

Version 1.0.0 - Monday Dec 1, 2025

Third-Party Libraries

FuseCommerce includes the following open-source libraries, used in compliance with their respective licenses:

Note! Future updates will be documented here. Check this section regularly for new features, improvements, and bug fixes.