Visual Image Search
AI-powered visual product search for WooCommerce. Let customers upload, drag-drop, capture, or paste images to find visually similar products instantly.
Overview & Features
What the plugin does and what's included out of the box
📷 Multiple Input Methods
Drag & drop, file browser, rear-facing camera capture, clipboard paste (Ctrl/Cmd+V), and URL-based image input.
🤖 AI Similarity Matching
CLIP vector embeddings, cosine similarity, and multi-signal scoring combining color, texture, shape, and semantic labels.
✂️ Image Cropping
Powered by Cropper.js — users can select a specific region before searching, improving accuracy on complex scenes.
⚡ Find Similar Button
Auto-injected "Find Similar" icon on every product card in the shop loop and on individual product pages.
🎭 3 Modal Styles
Choose between fullscreen, popup, or slide-panel presentation for the search interface.
♾️ Infinite Scroll
Seamless result loading with skeleton loading states —
📊 Analytics Dashboard
Search logs, fallback tracking, result counts, timing metrics, and a full admin analytics panel.
🔌 REST API
4 documented endpoints for headless storefronts, mobile apps, or custom integrations — fully authenticated.
Installation
Getting the plugin running on your WooCommerce store
WooCommerce Required. This plugin requires WooCommerce 6.0 or later and PHP 7.4+. It will not activate without WooCommerce present.
1. Upload plugin folder → /wp-content/plugins/advanced-image-search/
2. Activate through Plugins menu in WordPress admin
3. Navigate to Image Search → Settings and enter your license key
4. Choose your AI provider and enter the required API key (if applicable)
5. Go to Image Search → Dashboard and click "Re-index All Products"
6. Add [image_search] shortcode to any page to enable search
Background Indexing. On activation the plugin schedules two cron jobs: qsis_background_index (hourly, picks up new products automatically) and qsis_cleanup_temp (daily, purges expired uploads). Both are removed on deactivation.
Shortcodes
All four shortcodes — paste any of these into a page or post
The complete search experience in one shortcode. Renders the image upload area, camera/paste/URL inputs, optional image cropper, search controls (keyword refinement, category filter), and the live results grid with Add to Cart. This is the main shortcode for a dedicated "Search by Image" page.
| Attribute | Type | Default | Description |
|---|---|---|---|
| title | string | "Search by Image" | Heading text shown above the search interface |
| columns | number | 4 | Number of product columns in the results grid |
| style | full / compact / minimal | full | Layout density — full shows all controls, compact condenses the UI, minimal hides secondary options |
[image_search title="Find by Photo" columns="3" style="full"]
Renders only the results container and pagination — no upload UI. Useful when you want to embed results into an existing page layout alongside your own uploader widget or a custom trigger. Results populate via AJAX when a search is performed on the same page.
| Attribute | Type | Default | Description |
|---|---|---|---|
| columns | number | 4 | Number of product columns in the grid |
| per_page | number | 12 | How many results to load per page / per infinite-scroll batch |
[image_search_results columns="3" per_page="9"]
Place [image_search_uploader] and [image_search_results] on the same page to build a split layout — upload zone on the left, results on the right.
The upload interface without the results grid. Includes drag-and-drop, file browse, rear-camera capture, clipboard paste, and URL input — whichever methods are enabled in Settings. When an image is submitted, results appear via AJAX in a co-located [image_search_results] or in the global modal.
| Attribute | Type | Default | Description |
|---|---|---|---|
| compact | yes / no | no | Render a condensed single-line uploader suitable for embedding in a header or sidebar |
[image_search_uploader]
[image_search_uploader compact="yes"]
Embeds the admin dashboard panel on any frontend page. Visitors and regular customers see a permission-denied message. Only users with the manage_woocommerce capability can view the panel — typically administrators and shop managers.
Place this shortcode on a password-protected or members-only page to avoid exposing the permission-denied message to the public unnecessarily.
[image_search_admin]
Page Examples
Ready-to-use shortcode combinations for common page layouts
Dedicated Search Page
Page: "Search by Image"The simplest setup — drop the full shortcode on a new page. All upload methods, cropping, category filter, and results are included in one block.
[image_search columns="4" style="full"]Split Layout — Uploader + Results
Elementor / Block EditorPlace both shortcodes in a two-column layout block. The uploader fires AJAX and populates the results grid beside it — no page reload.
[image_search_uploader][image_search_results columns="3" per_page="9"]Compact Header Embed
Widget area / Header templateA minimal upload button that triggers the global modal — suitable for a site header or sidebar widget alongside the standard keyword search bar.
[image_search_uploader compact="yes"]Admin Control Panel
Page: "Image Search Admin"A private page for shop managers to view index status, trigger re-indexing, and access search analytics without going to wp-admin.
[image_search_admin]REST API
Four endpoints for headless storefronts, mobile apps, and custom integrations
All endpoints are under the /wp-json/qsis/v1/ namespace. Requests require a valid WordPress nonce (X-WP-Nonce header) or an Application Password for external clients.
The primary search endpoint. Accepts a multipart image file upload or a public image URL, runs it through the configured AI provider, and returns a ranked list of matching WooCommerce products.
| Field | Type | Required | Description |
|---|---|---|---|
| image | file | One of | Image file upload (JPEG, PNG, or WebP) |
| image_url | string | One of | Public URL of an image to search with |
| category_id | number | No | Restrict results to a WooCommerce category |
| keywords | string | No | Optional keyword refinement layered on top of image matching |
| per_page | number | No | Results to return (max controlled by Settings) |
{
"products": [ { "id": 42, "name": "...", "score": 0.87, "price": "...", "image": "..." } ],
"total": 18,
"labels": ["sneaker", "white", "leather"],
"provider": "clip_api",
"cached": false
}
Pass any WooCommerce product ID to retrieve visually similar products based on that product's already-indexed embedding. Powers the "Find Similar" button on product pages.
| Param | Type | Description |
|---|---|---|
| {id} | number | WooCommerce product post ID |
| per_page | number | (query string) Number of results to return |
GET /wp-json/qsis/v1/similar/42?per_page=8
Returns the current index status, total products, indexed count, AI provider in use, and key configuration flags. Useful for monitoring or external dashboards.
{
"total_products": 340,
"indexed": 338,
"provider": "builtin",
"license": "valid",
"cache_enabled": true,
"last_index_run": "2025-04-12 14:30:00"
}
Returns the list of product categories that can be used as a filter parameter when calling /search. Populate a category dropdown in your custom frontend with this.
[ { "id": 15, "name": "Shoes", "slug": "shoes", "count": 84 }, ... ]
AI Providers
Choose the matching engine that fits your budget and accuracy needs
| Provider | API Key | Embedding Type | Best For |
|---|---|---|---|
| Built-in | None | Color histogram + texture + shape feature hash | Free stores, basic matching without external services |
| CLIP API | Optional (self-hosted) | Real 512-dim CLIP/ViT vectors — cosine similarity | Best accuracy. Ideal when you run a CLIP service (e.g. Jina, self-hosted) |
| Google Vision | Required | Object labels + feature hash | Object-heavy catalogs (furniture, tools, food) |
| OpenAI Vision | Required | Semantic description + feature hash (gpt-4o-mini) | Fashion, materials, lifestyle products |
Similarity weights are adjustable. In Settings → Similarity you can tune the contribution of each signal — Embedding (default 40%), Color (25%), Labels (20%), Texture (10%), Shape (5%) — to optimize for your specific product catalog.
Settings Reference
All configurable options under Image Search → Settings
| Setting | Default | Description |
|---|---|---|
| Plugin Enabled | yes | Master switch — disabling stops all frontend output without deactivating |
| Search Scope | products | What to search: products, posts, or custom |
| Primary Color | #FF6A00 | Accent color used throughout the plugin UI — set via :root { --qsis } |
| Setting | Default | Description |
|---|---|---|
| Max Upload Size | 10 MB | Maximum file size for image uploads |
| Allowed Types | jpg, jpeg, png, webp | Accepted image MIME types |
| Enable Cropping | yes | Show Cropper.js region-selection step before searching |
| Enable Camera | yes | Enable rear-facing camera capture (required for FAB) |
| Enable URL Input | yes | Allow searching by pasting an image URL |
| Enable Paste | yes | Allow Ctrl/Cmd+V clipboard image paste |
| Setting | Default | Description |
|---|---|---|
| Results Per Page | 12 | Products shown per page or per infinite-scroll batch |
| Max Results | 24 | Hard cap on total results returned per search |
| Show Similarity Score | yes | Display match percentage badge on each product card |
| Show Add to Cart | yes | AJAX Add to Cart button directly on results |
| Show Price / Rating | yes | Show product price and star rating in results |
| Infinite Scroll | yes | Load more results as the user scrolls |
| Skeleton Loading | yes | Show animated placeholder cards while results load |
| Modal Style | fullscreen | fullscreen, popup, or slide |
| Find Similar Button | yes | Auto-inject "Find Similar" icon on shop loop and product pages |
| Search Bar Camera Icon | yes | Auto-inject camera icon into the WooCommerce search bar |
| Setting | Default | Description |
|---|---|---|
| Similarity Threshold | 25% | Minimum match score to include a product in results |
| Category Boost | yes | Boost products whose category matches AI-detected labels |
| Embedding Weight | 40% | Contribution of vector embedding similarity to the final score |
| Color Weight | 25% | Contribution of color histogram matching |
| Labels Weight | 20% | Contribution of AI-detected label similarity |
| Texture Weight | 10% | Contribution of texture analysis |
| Shape Weight | 5% | Contribution of shape matching |
| Setting | Default | Description |
|---|---|---|
| Cache Results | yes | Database-backed cache — identical searches skip reprocessing |
| Cache TTL | 3600 s | How long a cached result is valid (seconds) |
| Rate Limit | 30 / min | Max search requests per IP per minute |
| Lazy Load Images | yes | Lazy-load product images in the results grid |
| Setting | Default | Description |
|---|---|---|
| Log Searches | yes | Record each search (type, labels, result count, timing, fallbacks) |
| Log Retention | 90 days | How long search logs are kept before auto-deletion |
Custom Triggers
Open the search modal or camera from any element on your site
The plugin uses document-level click delegation, meaning you can attach trigger classes to any HTML element — buttons, links, images, divs — and the JS will respond automatically. No extra JavaScript required.
Add this class to any clickable element to open the visual search modal. On mobile it opens the full modal with all input options; on desktop it opens based on your Modal Style setting (fullscreen, popup, or slide).
Visual Search
Add this class to open the fullscreen camera capture screen directly, without going through the modal first. After capture, the photo is automatically submitted for search. Requires Enable Camera to be on in Settings.
This is the same trigger used internally by the FAB button. You can use it to create your own branded camera button anywhere on the page.
The smart search-bar variant. On mobile it opens the fullscreen camera; on desktop it opens the search modal. This is what the plugin auto-injects into the WooCommerce search bar when Search Bar Camera Icon is enabled — you can also use it manually in a custom search bar.
Add this class plus a data-id attribute with a WooCommerce product ID to trigger a visual similarity search for that specific product. Opens the modal and loads results automatically. This is what the plugin injects on shop loop cards — you can use it in custom layouts too.
| Attribute | Type | Description |
|---|---|---|
| data-id | number | WooCommerce product post ID to search visually similar products for |
JavaScript API
Two global functions are exposed on window for use in custom scripts or inline onclick handlers.
| Function | Description |
|---|---|
| window.qsisInit() | Re-initialises event binding. Call this if you inject modal HTML into the DOM after page load (e.g. from a page builder or AJAX). |
| window.qsisOpenCamera() | Programmatically opens the fullscreen camera screen. Equivalent to clicking a .qsis-camera-trigger element. |
JavaScript Event
After every search the plugin fires a jQuery event on document you can hook into for custom integrations (analytics, Elementor, third-party grids).
$(document).on('qsis:results', function(e, data, productIds, isAppend) {
// data — full response object (results, labels, colors, pages)
// productIds — flat array of matched product IDs in score order
// isAppend — true when this is a "load more" / infinite scroll batch
console.log('Matched product IDs:', productIds);
});
The qsis:results event is how the Elementor integration works internally — it receives the product IDs and redirects with ?qsis_product_ids=… to filter the Loop Grid. You can use the same event to drive any custom product grid.
Body State Class
While the modal or camera is open, the plugin adds qsis-overlay-open to . Use this to hide or show other elements during an active search session.
body.qsis-overlay-open .my-chat-widget {
display: none !important;
}
Floating Action Button (FAB)
A persistent camera button that floats over your shop pages
The FAB is a floating camera icon that sits in the corner of the screen and opens the visual search modal on tap. It requires both FAB Enabled and Enable Camera to be turned on in Settings.
| Setting | Values | Default | Description |
|---|---|---|---|
| FAB Enabled | yes / no | yes | Show or hide the floating button globally |
| FAB Pages | all / shop_product / shop / product / custom | shop_product | Which pages the FAB appears on — shop_product covers all archive and single product pages |
| Custom Pages | string | — | Comma-separated page IDs, slugs, or WC keywords (shop, cart, checkout) when FAB Pages is set to custom |
| FAB Position | bottom-right / bottom-left / bottom-center | bottom-right | Corner or edge where the button anchors |
| Offset X | pixels | 24 | Distance from the horizontal edge in pixels |
| Offset Y | pixels | 24 | Distance from the bottom edge in pixels |
Set FAB Pages → custom and enter specific page IDs separated by commas to show the FAB only on hand-picked pages (e.g. a custom landing page or collection page outside the normal WooCommerce structure).
Elementor Integration
Use visual search results to drive an Elementor Loop Grid widget
Instead of rendering results in the plugin's own grid, you can route matched product IDs into an existing Elementor Loop Grid (or Posts widget) on the same page. This lets you use Elementor's skin system for full design control over the result cards.
Setup Steps
1. In Elementor, add a Loop Grid / Posts widget to your search results page.
2. In the widget's Query settings, set the Query Type to "Custom" and
enter "qsis_visual_search" as the Custom Query ID.
3. In Image Search → Settings → Results Display, set Result Target to
"elementor" and enter the widget's CSS ID in "Elementor Grid ID".
4. When a search runs, the plugin redirects with ?qsis_product_ids=1,2,3
and the Loop Grid automatically filters to those products in score order.
The qsis_visual_search custom query hook intercepts both the Elementor query callback and the main WP_Query for the page, preserving the similarity score order via orderby: post__in. You can also pass a custom CSS selector via Result Target → custom_selector if you're using a non-Elementor product grid.
Product Indexing
How product images are processed and stored for fast matching
Before visual search can work, each product's images must be processed and their feature vectors stored in the plugin's database tables. This is called "indexing".
🔄 Auto-Indexing
When enabled, new or updated products are automatically queued and processed. The background cron runs hourly in batches.
🖼️ Gallery Support
When Index Gallery is enabled, all gallery images are indexed alongside the main product image — not just the featured image.
🔀 Variation Support
Variation images can be indexed separately so that color/pattern variants appear correctly in results.
📦 Batch Size
Default batch is 10 products per cron run. Increase on high-memory servers or decrease if you hit timeouts.
Database Tables
| Table | Contents |
|---|---|
| qsis_embeddings | Vector embeddings per image — up to 512 dimensions depending on provider |
| qsis_product_map | Maps product IDs to their embedding IDs, image type (main / gallery / variation) |
| qsis_search_log | Full search analytics: input type, detected labels, result count, timing, fallback flags |
| qsis_search_cache | Cached search results with TTL, hit counter, and filter-awareness flags |
Re-indexing clears existing data. Use the "Re-index All Products" button in the admin Dashboard only when changing AI providers or after bulk-importing products. The background indexer handles routine updates without clearing.
License
Activating and managing your plugin license
A valid license is required for all functional features (search, indexing, REST API, FAB). The Settings and License pages are accessible without activation so you can always enter or update your key.
| State | What's available |
|---|---|
| No license / Invalid | Settings page, license activation form. All search features disabled. Admin notice shown. |
| Valid license | All features — indexer, search, REST API, frontend shortcodes, FAB, analytics. |
Enter your license key at Image Search → Settings → License. License validity is checked periodically via a scheduled cron event (qsis_license_check).
