SwiftSearch for Typesense

SwiftSearch replaces your default WordPress search with an instant, typo-tolerant search engine powered by Typesense. It's designed for speed, converting your visitors into customers with lightning-fast results.

1. Installation

2. Configuration & Indexing

SwiftSearch simplifies index management with a robust dashboard.

API Keys Best Practice

For optimal security, we recommend using two separate API keys:

• Admin Key: Used by the plugin to create schemas and index content securely from the backend.
• Search-Only Key: Used by the frontend/browser to fetch results. This key is read-only and safe to expose.

Reliable Background Indexing

Click "Index All" to start building your search index. The plugin uses the industry-standard Action Scheduler (the same library used by WooCommerce) to process thousands of items in the background without slowing down your site.

3. Features & Capabilities

Full Technical Feature List

4. Displaying the Search

To display the clean search bar anywhere on your site (header, sidebar, or inside a page), use the shortcode:

[swift_search]

Advanced Options

You can customize the search behavior using specific attributes:

• placeholder: Custom placeholder text (Default: "Search...").
• limit: Maximum number of results to display (Default: 10).
• show_thumbnail: "true" to show images, "false" for text-only.
• post_types: Comma-separated list (e.g. "product,post").

Example Usage

[swift_search placeholder="Find products..." limit="8" post_types="product" show_price="true"]

5. Theming & Customization

The search interface is designed to inherit your theme's fonts, but you can override styles using standard CSS.

/* The Outer Wrapper */
.ss-wrapper { 
    max-width: 600px; 
}

/* The Search Input Box */
.ss-search-box input { 
    border-radius: 8px;
    border: 2px solid #e5e7eb;
}

/* Highlighted Matches */
.ss-hit-title mark { 
    background-color: rgba(255, 0, 85, 0.1);
    color: #ff0055;
}

6. Developer Hooks

SwiftSearch provides several filter hooks and DOM events allowing developers to programmatically customize indexing, styling, search behaviors, and track events.

PHP Actions & Filters

swift_search_async_index_post (Action)
Trigger a background re-index for a specific Post ID.

// Trigger re-index for Post ID 123
do_action('swift_search_async_index_post', 123);

swift_search_should_index_post (Filter)
Conditionally control whether a post should be indexed into Typesense.

add_filter('swift_search_should_index_post', function($should_index, $post_id, $post) {
    // Example: Exclude products that are out of stock
    if ($post->post_type === 'product') {
        $product = wc_get_product($post_id);
        if ($product && !$product->is_in_stock()) {
            return false;
        }
    }
    return $should_index;
}, 10, 3);

swift_search_post_document (Filter)
Modify or append custom fields to the document data array before it gets synced to Typesense.

add_filter('swift_search_post_document', function($document, $post_id, $post) {
    // Example: Add a custom ranking score field
    $document['popularity_score'] = (int) get_post_meta($post_id, '_total_sales', true);
    return $document;
}, 10, 3);

swift_search_shortcode_args (Filter)
Modify the parsed shortcode attributes dynamically based on page context.

add_filter('swift_search_shortcode_args', function($args, $atts) {
    // Example: Change the search input placeholder on product archive pages
    if (is_post_type_archive('product')) {
        $args['placeholder'] = 'Search our shop...';
    }
    return $args;
}, 10, 2);

swift_search_vars (Filter)
Filter the localized JavaScript configuration object (swiftSearchVars) passed to the frontend.

add_filter('swift_search_vars', function($vars, $settings) {
    // Example: Dynamically adjust the Typesense API Key for specific user roles
    if (current_user_can('wholesale_customer')) {
        $vars['apiKey'] = 'SPECIAL_READ_ONLY_KEY_FOR_WHOLESALE';
    }
    return $vars;
}, 10, 2);

JavaScript DOM Events

JavaScript events are dispatched from the search container wrapper (#swift-search-wrapper) and bubble up. You can listen to them on the wrapper or on the document.

swift-search:before-search
Fires right before search request parameters are sent to Typesense. Allows modification of search parameters or canceling the request entirely via e.preventDefault().

document.addEventListener('swift-search:before-search', function(e) {
    const query = e.detail.query;
    const searches = e.detail.searches; // Passed by reference; can be modified directly

    // Example: Dynamically append a hardcoded filter parameter
    searches.forEach(search => {
        search.filter_by = search.filter_by 
            ? `${search.filter_by} && in_stock:=true` 
            : 'in_stock:=true';
    });
});

swift-search:render-hit
Fires for each individual search card before it is appended to the grid. Allows modification of classes, content, or styling of the card element.

document.addEventListener('swift-search:render-hit', function(e) {
    const card = e.detail.card;       // The DOM element of the card
    const hit = e.detail.hit;         // Raw Typesense hit object
    const collection = e.detail.collection; // 'posts', 'terms', or 'users'

    // Example: Add a custom ribbon tag to products priced over $100
    if (collection === 'posts' && hit.document.price > 100) {
        const badge = document.createElement('div');
        badge.className = 'ss-badge ss-badge-premium';
        badge.innerText = 'Premium';
        card.appendChild(badge);
    }
});

swift-search:results-rendered
Fires after search results, headers, and pagination are fully rendered on the page. Ideal for firing analytics scripts or custom UI initializations.

document.addEventListener('swift-search:results-rendered', function(e) {
    const data = e.detail.data;             // Raw multi_search response data
    const totalFound = e.detail.totalFound; // Total matches count

    // Example: Push event tracking to Google Tag Manager / Analytics
    if (typeof gtag !== 'undefined') {
        gtag('event', 'search', {
            search_term: data.results[0].request_params.q,
            results_count: totalFound
        });
    }
});

7. Troubleshooting & FAQ