1. Installation

2. First Steps

After installation, visit your store’s frontend. You should see the NPsearch input in your header, replacing the native PrestaShop search bar.

NPsearch widget replaces the native search bar in your theme’s header

3. Search Overlay

When a customer clicks the search input, a full overlay opens with:

• Search input with debounced typing (300ms)
• Popular categories as clickable chips
• Popular brands as clickable chips
• Recent searches (stored in localStorage)

Empty state shows popular categories and brands for quick navigation

4. Search Results

As the customer types, results appear in real-time with:

• Product cards with image, name, price, and stock status
• Result count and query highlighting
• Faceted filters (categories, brands, in-stock toggle)
• Sort options (relevance, price, name, newest)
• Pagination for large result sets

Search results for “mug” — product cards with images, prices, and stock badges

5. Search Page Integration

NPsearch integrates with PrestaShop’s native search page via the ProductSearchProviderInterface. When customers submit the search form or press Enter, they are taken to the standard search results page — powered by NPsearch’s engine.

Full search page with product grid, powered by NPsearch scoring engine

6. Backoffice Configuration

Go to Modules → NPsearch → Configure to access:

Settings

• Custom search selectors: CSS selectors for your theme’s native search elements. NPsearch will intercept clicks on these and open the overlay. Example: #my-search-btn, .header-search-icon
• Hide native search elements: Automatically hide detected native search bars so only NPsearch is visible.

Search Index

• Index status: Shows how many products are indexed
• Rebuild Index: One-click button to re-index all products. Useful after bulk imports.

The index updates automatically when you add, edit, or delete products via hooks.

7. Synonym Management

NPsearch ships with 585+ synonym groups across 23 sectors. You can manage them in the backoffice:

Pre-loaded sectors

How synonyms work

When a customer searches for sneakers, NPsearch expands the search to also match zapatillas, tenis, bambas, deportivas. This happens transparently — the customer sees normal results.

Custom synonyms

In the backoffice, you can:

• Add new synonym groups (group name + pipe-separated terms)
• Edit existing groups
• Activate/Deactivate groups per sector
• Re-seed default synonyms if you accidentally delete them

8. Analytics Dashboard

The backoffice shows search analytics for the last 30 days:

• Total searches
• Zero-result rate (% of searches with no results — aim for <5%)
• Fuzzy fallback rate (% of searches that needed fuzzy matching)
• Popular searches (top 20 queries with search count)
• Zero-result queries (top 20 failed queries — add synonyms or products for these!)
• Daily search volume (last 14 days)

9. Theme Compatibility

NPsearch is designed to work with any PrestaShop 8+ theme:

• Classic (PS8 default) — fully tested
• Hummingbird (PS9 default) — fully tested
• Custom themes — works via hook auto-detection + custom selector config

How it works

1. NPsearch renders its search widget via the displayTop hook
2. On page load, JavaScript detects the native search bar and moves our widget to its position
3. The native search is hidden (CSS hides the form, JS intercepts clicks)
4. If auto-detection fails, you can specify custom selectors in the backoffice

Troubleshooting

If NPsearch doesn’t replace your theme’s search:

1. Open browser DevTools (F12)
2. Find your theme’s search input/button element
3. Copy its CSS selector (e.g., .header-search-btn)
4. Paste it in Back Office → NPsearch → Custom search selectors

10. Mobile Experience

NPsearch is fully responsive:

• Overlay goes fullscreen on mobile (<768px)
• Product grid adapts (2 columns on mobile, 4 on desktop)
• Input uses 16px font to prevent iOS Safari zoom
• Touch-friendly targets (44px minimum)

Mobile view — search widget integrates naturally in the header

11. FAQ