# Ajax Search Lite for WordPress documentation


# Search Shortcode

The search shortcode

![Search shortcode and the PHP version for themes](/files/1ANkdwh8UcvnW6VE6XnW)

The search shortcode can be used within post/page or any custom post type contents, as well as site headers, footers or any other template parts.

### Regular shortcode

Use this shortcode within posts/pages or any custom post type contents, [menu items](/search-shortcode/shortcode-as-a-menu-item), template editor blocks or in any widgets, which support shortcodes.

`[wpdreams_ajaxsearchlite]`

### Shortcode for code/template files directly

The following shortcode is to be used in template/plugin files directly.

```
<?php echo do_shortcode('[wpdreams_ajaxsearchlite]'); ?>
```


# Shortcode as a menu item

The search shortcode can be used as a menu element

It is possible to use the [search box shortcode](/search-shortcode) in a menu as the title field. The menu item will be automatically replaced with the search bar. This simple guide will help you achieve that.

1\) Under the **Appearence -> Menus** submenu open up (or create) the menu you want to edit.

![](http://i.imgur.com/QqCp0qu.png)

2\) Click on the **Custom Links** item and as the *URL* enter anything (I used the '#' character in this example), and as the *Link Text* paste the search shortcode, then click the **Add to Menu** button.

![](/files/rKPRQl72uovOHbyL3XeJ)

3\) That's it. The menu item is created, now you can move it like any other one.

![](/files/NnvXNOiRTNkdRiumbUz0)

4\) **Make sure to save the menu**, and the search should appear as a menu item on the front-end.


# General Options


# Sources and Basics

Searching custom post types, selecting fields to search, post statuses etc..

![](/files/-MXgHQ5KsbUBTaXW6U1N)

### Searching posts, pages and any other custom post types

To search custom post types, drag the post types from the left side of the container to the right side.

![Custom post types option](/files/-MXgHe12z52fcVJOwrGk)

### Searching titles, contents, excerpts and other fields

On the same options panel, scroll down to select which fields to search within.

![](/files/-MXgHvved8yiN7mvOuPW)

### Searching in custom fields

You can either choose to search all custom fields, or search and select which custom fields to search within.

![Searching all custom fields](/files/-MXgI8gxxOKkGIBbfwhn)

For selecting custom fields, first turn off the `Search all custom fields?` option, then enter the custom field name to the search field - then drag it to the right side of the option.

{% hint style="info" %}
If the custom field name does not appear in the list (like some Advanced Custom Fields **ACF** fields after creation), that means it is not yet have been assigned a value. When you create your first post with the newly created fields, and assign a value to it, it will appear in the list.
{% endhint %}

![](/files/-MXgIf3lC3Yl9R3N3fx6)

#### Known custom fields

* **\_sku** - WooCommerce product SKU field

### Searching by categories, tags and other taxonomy terms

By turning on the `Search in terms?` option, the search within taxonomy terms (for posts and post types) is enabled.

![](/files/-MXgJUayMBqiWI_Rl6YU)

### Post statuses and password protected posts

![](/files/-MXgJmVeZeMuqphHRInA)

By default password protected published posts are returned. You can add post statuses to the list (comma separated!), as well as turn off displaying password protected posts.


# Search logic

Search logic, exact matching, fuzzy matches

![](/files/-MXgTLStE9jvl_DiakPu)

### Exact matching

When exact matching, the plugin always treats the search input as a single search keyword.

![](/files/-MXgTQnlVUrjPvbAe6N9)

#### Exact match location

| Keyword      | Fields                                                       | Location             | Match?  |
| ------------ | ------------------------------------------------------------ | -------------------- | ------- |
| hello wor    | <p><em>Post Title:</em><br><strong>Hello wor</strong>ld!</p> | Anywhere             | **YES** |
| llo wo       | <p><em>Post Title:</em><br>He<strong>llo wo</strong>rld!</p> | Anywhere             | **YES** |
| orld!        | <p><em>Post Title:</em><br>He<strong>llo wo</strong>rld!</p> | Anywhere             | **YES** |
| hello wor    | <p><em>Post Title:</em><br><strong>Hello wor</strong>ld!</p> | Starting with phrase | **YES** |
| llo wo       | <p><em>Post Title:</em><br>He<strong>llo wo</strong>rld!</p> | Starting with phrase | **NO**  |
| orld!        | <p><em>Post Title:</em><br>Hello w<strong>orld!</strong></p> | Starting with phrase | **NO**  |
| hello wor    | <p><em>Post Title:</em><br><strong>Hello wor</strong>ld!</p> | Ending with phrase   | **NO**  |
| llo wo       | <p><em>Post Title:</em><br>He<strong>llo wo</strong>rld!</p> | Ending with phrase   | **NO**  |
| orld!        | <p><em>Post Title:</em><br>Hello w<strong>orld!</strong></p> | Ending with phrase   | **YES** |
| hello wor    | <p><em>Post Title:</em><br><strong>Hello wor</strong>ld!</p> | Complete match       | **NO**  |
| llo wo       | <p><em>Post Title:</em><br>He<strong>llo wo</strong>rld!</p> | Complete match       | **NO**  |
| orld!        | <p><em>Post Title:</em><br>Hello w<strong>orld!</strong></p> | Complete match       | **NO**  |
| hello world! | <p><em>Post Title:</em><br><strong>Hello world!</strong></p> | Complete match       | **YES** |

### Search keyword logic (fuzzy logic)

![](/files/-MXgVj26RNF6v9LF0fRx)

When exact matching is disabled, then there are **4 possible logics** to choose from:

* OR (default)
* OR with exact word matches
* AND
* AND with exact word matches

The default is "OR". For more information about the logics please read [search logics explained](/general-options/search-logic/search-logics-explained)


# Search logics explained

The logic on the same or across the separate fields for each keyword (title, content, excerpt etc..)

## OR

Match is found if any of the search keywords is part of the content. It's the least strict of all possible options - it returns many results, finds almost anything.

| Keyword        | Fields                                                                                                                                      | Match? |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| hello          | <p><em>Post Title:</em><br><strong>Hello</strong> big world!</p><p><br><em>Post Content:</em> <br>Robot here!</p>                           | YES    |
| hello wor      | <p><em>Post Title:</em></p><p><strong>Hello</strong> big <strong>wor</strong>ld!</p><p></p><p><em>Post Content:</em> </p><p>Robot here!</p> | YES    |
| hello robot    | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p><strong>Robot</strong> here!</p>  | YES    |
| hel bot        | <p><em>Post Title:</em></p><p><strong>Hel</strong>lo big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bot</strong> here!</p>  | YES    |
| help bot hello | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bo</strong>t here!</p>  | YES    |
| hello science  | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Robot here!</p>                   | YES    |

## OR with exact word matches

Similar to the simple OR, but at least one keyword must match a whole word. Partial results are not accepted.

| Keyword        | Fields                                                                                                                                      | Match?                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| hello          | <p><em>Post Title:</em><br><strong>Hello</strong> big world!</p><p><br><em>Post Content:</em> <br>Robot here!</p>                           | YES                                      |
| hello wor      | <p><em>Post Title:</em></p><p><strong>Hello</strong> big <strong>wor</strong>ld!</p><p></p><p><em>Post Content:</em> </p><p>Robot here!</p> | YES                                      |
| hello robot    | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p><strong>Robot</strong> here!</p>  | YES                                      |
| hel bot        | <p><em>Post Title:</em></p><p><strong>Hel</strong>lo big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bot</strong> here!</p>  | <p>NO</p><p>(whole word don't match)</p> |
| help bot hello | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bo</strong>t here!</p>  | YES                                      |
| hello science  | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Robot here!</p>                   | YES                                      |

## AND

Every keyword must match at least partially the content.

| Keyword        | Fields                                                                                                                                      | Match?  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| hello          | <p><em>Post Title:</em><br><strong>Hello</strong> big world!</p><p><br><em>Post Content:</em> <br>Robot here!</p>                           | YES     |
| hello wor      | <p><em>Post Title:</em></p><p><strong>Hello</strong> big <strong>wor</strong>ld!</p><p></p><p><em>Post Content:</em> </p><p>Robot here!</p> | YES     |
| hello robot    | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p><strong>Robot</strong> here!</p>  | **YES** |
| hel bot        | <p><em>Post Title:</em></p><p><strong>Hel</strong>lo big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bot</strong> here!</p>  | **YES** |
| help bot hello | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bo</strong>t here!</p>  | NO      |
| hello science  | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Robot here!</p>                   | NO      |

## AND with exact word matches

The most strict search logic. Every keyword must match a whole word in the content.

| Keyword        | Fields                                                                                                                                      | Match?  |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| hello          | <p><em>Post Title:</em><br><strong>Hello</strong> big world!</p><p><br><em>Post Content:</em> <br>Robot here!</p>                           | YES     |
| hello wor      | <p><em>Post Title:</em></p><p><strong>Hello</strong> big <strong>wor</strong>ld!</p><p></p><p><em>Post Content:</em> </p><p>Robot here!</p> | NO      |
| hello robot    | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p><strong>Robot</strong> here!</p>  | **YES** |
| hel bot        | <p><em>Post Title:</em></p><p><strong>Hel</strong>lo big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bot</strong> here!</p>  | NO      |
| help bot hello | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Ro<strong>bo</strong>t here!</p>  | NO      |
| hello science  | <p><em>Post Title:</em></p><p><strong>Hello</strong> big world!</p><p></p><p><em>Post Content:</em></p><p>Robot here!</p>                   | NO      |


# Triggers and redirection to results page

Live search trigger actions and the redirection to the results page actions

![](/files/-MXptXVFDZBs0G_shS29)

### Live search triggers

![](/files/-MXptoLn_PTi01BHvD4l)

* *Trigger search on facet change* - live search trigger, when the user changes an option on the settings drop-down
* *Trigger search when typing* - triggers the live search during typing to the search input
* *Character count* - only apply the triggers, when this number of characters were entered

### Redirection to the results page

Redirection can be set for both the magnifier click and the return (enter) key events.

![](/files/-MXpuZrLUD71RrayIOT8)

When using WooCommerce and searching for products use the *Redirect to: WooCommerce results page* value.

#### Custom redirect URL

When using a custom permalink structure for the search queries, you can adjust the redirection to the same destication via this option. The `{phrase}` pseudo-variable is replaced with the current search phrase.

{% hint style="warning" %}
This will not change the results page URL to a custom page URL - this option only redirects to the given location. If you want to change the results page URL slug, check out [online tutorials](https://www.wpbeginner.com/wp-tutorials/how-to-change-the-default-search-url-slug-in-wordpress/).
{% endhint %}

### Search results page override

![](/files/-MXpwQTHzxvcyTnfCHcO)

When enabled, the plugin will try to override the search results page with the same results as on the live search list.

{% hint style="warning" %}
The plugin can not change the layout/design of the results page, that is a theme controlled feature. All it can do is send which items to display as results, the rest is up to the theme.
{% endhint %}


# Results page live loader

When this feature is Enabled, the plugin will try to load the results - without reloading the results page.

`General Options -> Results page live loader`

![](/files/Nohz68RWOV9R6GOcR3Fn)

{% hint style="warning" %}
**Disclaimer:** Live loading items to a page causes the script event handlers to detach on the affected elements - if there are interactive elements (pop-up buttons etc..) controlled by a script within the results, they will probably stop working after a live load. \
This cannot be prevented from this plugins perspective.

There is **no guarantee** that this feature will work with any theme/website out there. It very highly depends on the actual website structure as well as the overall configuration.
{% endhint %}

![](/files/3JN17eb6wPSiLBrVTG32)

#### Results container jQuery element selector

Default value: **#main**

This is the selector that the script tries to match, when the new results page is loaded via AJAX. The script then replaces the old content within this selector with the new ones.

{% hint style="warning" %}
&#x20;If you don't know what this means, then leave this options as it is by default
{% endhint %}

#### How can I find this selector for my theme?

If you are not a developer, your best bet is to ask the author of your current theme, he might know how to get the selector to target the results page container.

You can also contact us [via support](https://wordpress.org/support/plugin/ajax-search-lite/), we might be able to help - but please note that we cannot guarantee this feature to work correctly in every case.

The only possible way is using the browser developer console or via the page source. Unfortunately there is no guide we could provide for this, as it would exceed the contents of this documentation.


# Ordering

Primary and secondary search results ordering

![](/files/-MXqUiNXDt8PPLQBvjRd)

### Primary ordering

This is used first, when fetching the results.

### Secondary ordering

When the primary ordering of matching results is the same, then the secondary ordering is used.

Ex.:  Primary -> Relevance, Secondary -> Date descending\
Result1 and Result2 has the same relevance, so the secondary ordering kicks in, and orders by the date published descending.


# Autocomplete & Keyword Suggestions

Google autocomplete and keyword suggestions

![](/files/-MXqNZ0Sbaqzm-Prf05M)

### Autocomplete

Autocomplete triggers whenever the user starts typing to the search input.

![](/files/-MXqNuO2klTWUaqXUDvF)

### Keyword suggestions

Keyword suggestions are displayed whenever there are no results matching the search criteria.


# Image Settings

Live search results images

![](/files/-MXqOUORI2rQKzftRYZb)

### Width, height and background position

![](/files/-MXqOfFwFoCzbTveIgYL)

Width and height should be numeric values, the pixel prefix is automatically appended. The display mode changes whether the image should cover the whole \[width x height] container, or should it be contained respecting the aspect ratio.

![Background display mode](/files/-MXqQ4kjMbXlviEy4tT_)

### Image sources

![](/files/-MXqQSJxdXQeTe5MjtPF)

The plugin parses through the primary, then the alternative image sources, until it finds an image to display. If no image is found, the default image URL is used.

#### Image number for the parser

![](/files/-MXqR85ErDsAlABwUdFJ)

By default the first image is returned, whenever the parser finds an image within each source. This feature is useful, when for example there are multiple images within the post contents, and you want to skip the first *N* of them.

#### Exclude images by file names

![](/files/-MXqRDP6rKcFZCM_ndFY)

Comma separated list of strings, whenever any of these is found, the image is skipped and the parser proceeds to the next possible image.


# Frontend search filters

Generic and Post category filters

![](/files/-MXqn42SCy_51ZjW1oY0)

### Generic Filters

Exact match, search in title and content checkboxes can be turned on an off.

![Generic Filters](/files/-MXqn6TLvlPtkwoE_g7D)

The exact match checkbox status (checked or unchecked) depends on if the exact matching is enabled on the [General Options -> Search logic](/general-options/search-logic) panel.

The title and content checkbox statuses depend if the `Search in title` and `Search in content` options are enabled under the [General Options -> Sources](/general-options/sources-and-basics) panel.

### Custom Post Type Filters

![](/files/-MXqnHels8Vob9Qmt11Q)

Choose the post type filters from the left side, drag them to the right side to activate. The filter checkbox statuses (checked or unchecked) depend if the custom post type is selected under the [General Options ](/general-options/sources-and-basics)panel.

### Post category Filters

![](/files/-MXqo7n0V_MQj_vp9io1)

When enabled, all the categories are displayed within the filter. Drag the categories you want to exclude from the left side of the `Select which categories to exclude` selector to the right side.


# Layout Options


# Theme and Customization

![](/files/-MXqoygYr7K86oJRf9hQ)

### Search theme

![](/files/-MXqp2alyxlJ2_0PBS4w)

There are several themes available to choose from. Some of the aspects can be modified as well - such as the width, margin, font, background colors etc..

{% hint style="warning" %}
After making changes to the search theme make sure to always clear all cache - including site cache, minify, asset, CDN, cloudflare and browser cache.
{% endhint %}


# Results layout and fields shown

![](/files/-MXqqjw7_F3-LuAhRd_z)

### Result coulumns

The results can be divided into multiple columns (by default 1).&#x20;

![](/files/-MXqr3YMhzFwv-Ffazyr)

Setting multiple columns will yield the following layout.

![](/files/-MXqrIERsGV5Q_11hlFR)

### Viewport size and scrolling

The plugin dynamically adjusts the viewport size from the average results height (by default to 4 items). Changing this viewport size will increase/decrease the results drop-down overall height.

![](/files/-MXqrdalB0z4w7kBSlCn)

Setting the viewport to a very high number like 999 will result in a very long results box, without the scrollbar.

### Fields and context

![](/files/-MXqrrt-5jQ5OOcdyAO5)

#### Description context

When enabled, the plugin will try displaying the results description from around the search phrase - instead of showing the description text from the beginning. It does it to a certain depth of characters.

![](/files/-MXqsVPIwKU6_94PGH_K)


# Results box behavior

![](/files/-MXqspH1JcjivjxhlA_B)

* `Open the results in a new window?` - When enabled, clicking on the results will open them in a new browser window
* `Scroll the window to the result list?` - When enabled, the plugin will scroll the browser window to the results list.
* `Make the whole result area clickable?` - When disabled, only the live result titles are clickable
* `Close result list on document click?` - When enabled, clicking anywhere on the page will close the search results container
* `Show the close icon?` - When enabled, a close (X) icon is displayed within the search input - which closes the search results container when clicked.


# Keyword highlighter

Keyword highlighting in live results list and on single results pages

## Live results list highlighting

![](/files/-MXqtwLu5B4dE0fiTC6I)

It is possible to highlight the search phrase in the **live results** list. Within these options you can change the:

* Highlighter text color and background
* and to highlight whole words or partial words as well

## Single result page keyword highlighting

{% hint style="warning" %}
The single result (clicking a result on the live results list) is not the same as the search results page. This feature does not work on the search results page.
{% endhint %}

![](/files/-MXquAwfnQ23hTktaTHl)

### Scrolling to the first keyword match

Whenever the `Scroll to the first keyword match if possible?` option is enabled, the plugin will try to scroll to the first keyword match, after redirecting to the single result.

If you want to programatically specify a part of the result page to apply the highlighter and scroll feature on, then use the `Result page content jQuery element selector` option. This is useful when the search phrase might appear outside of the post body container (in a widget, footer or menu etc..), and you want to make sure those appearances are not highlighted.


# Advanced Options


# Title and Content fields

During the search post-process, the plugin parses the Post/Page/CPT titles and the contents, as defined by these fields.

![](/files/-MWF6CyjPMOzSu2gq90v)

## Examples

### Custom field content as Title or Description

It is possible to define a single, text based custom field as the title or description field.

![](/files/-MWF6M47uh1aQPBJUSFN)

### Yoast SEO title and meta description custom fields

The Yoast SEO plugin uses the folling custom fields to store the custom title and meta desctiption fields:

* \_yoast\_wpseo\_title
* \_yoast\_wpseo\_metadesc

### All in one SEO plugin meta title and desctiption custom fields

The All in One SEO plugin uses the following custom fields:

* &#x20;\_aioseop\_title
* &#x20;\_aioseop\_description


# Advanced Title and Content fields

Adding custom fields, taxonomy terms, WooCommerce add to cart, star rating, price to the results.

This feature is identical to the Pro version, please check the documentation [here](https://documentation.ajaxsearchpro.com/advanced-options/advanced-title-and-description-fields).

{% embed url="<https://www.youtube.com/watch?v=CSL7HN337j8>" %}
Advanced Title and Content Fields
{% endembed %}


# Keyword Exceptions

Removing keywords from the search phrases entered

![](/files/-MWF7Yjs7lNn4OouU4ID)

### Keyword exceptions - replace anywhere

Keywords specified in this option are replaced in order within the search phrase with an empty string - mathing anywhere within the search string

#### Example

Defining the following keyword exceptions:

`A123, B456, 999`

..and searching the phrase: "*A**A123*** ***A123** 88**999**CC **999** B**B456**7" ..*&#x77;ill result in a search for: \
"*AA 88CC B7 "*

### Keyword exceptions - replace *whole words only*

Keywords specified in this option are replaced in order within the search phrase with an empty string - mathing only whole words

#### Example

Defining the following keyword exceptions:

`A123, B456, 999`

..and searching the phrase: "*AA123 **A123** 88999CC **999** BB4567" ..*&#x77;ill result in a search for: \
"*AA123 88999CC BB4567"*


# Javascript Compatibility

## Javascript Source and loading methods

![](/files/dLiLOSwW7kengSQRrcVn)

### Javascript Source option

{% hint style="warning" %}
**Legacy** scripts are built based on **jQuery** and compatible with **Microsoft Internet Explorer 10+** browsers. The non-legacy (Minified and Non-minified) are using modernized and more efficient [ES6](https://www.w3schools.com/js/js_es6.asp) javascript - therefore some features are compatible with **Microsoft Edge** and upwards.
{% endhint %}

{% hint style="warning" %}
The Legacy scripts are getting deprecated and will be **removed in the first 2022** release, and all installations will swap to the non-legacy version automatically when updated.
{% endhint %}

* **Non minified** - Non minified javascript source files (non-legacy, does not require jQuery)
* **Minified** - Minified javascript files (non-legacy, does not requiery jQuery). Default and **highly** recommended.
* **Legacy Non minified** & **Legacy Minified** - Same as above, but using the legacy jQuery versions of the scripts
* **Legacy Non minified scoped** & **Legacy Minified Scoped** - More robust versions with a scoped jQuery script

#### Which script source should you use?

Usually the best is used the **Minified** version, from both the legacy and non-legacy options. Even if you are using a cache plugin with asset minification feature, using the minified version should cause no issues - as further minification is not applied in most cases.

If you are experiencing issues with a cache/minify plugin, try the **Non-minified** method instead.

#### What there are issues, and only the Legacy versions work for me?

You should definitely report that to us [via our support](https://wp-dreams.com/open-support-ticket-step-1/). The legacy scripts are going to be removed, so please make sure to report any issues to us, so we can patch them as soon as possible.

### Javascript loading method option

![](/files/cUYUER5IssFM4VwdnnWY)

This option is only available when a non-legacy source is selected.

* **Classic** - The plugin core scripts are merged into a single file (+ a prerequesite file). This file contains all of the core functions, but most likely it contains code you may not need. This option is the most robust choice, will most likely work in all cases.
* **Optimized** - The plugin will enqueue more script files, however only the ones definitely required. It can save a lot of page loading time.
* **Optimized asynchronous** - Only a single script file is enqueued, then this file will request the rest of the required script files in the background. It should be the fastest.

#### Which one should you choose?

* Choose **Classic**, when the search bar is not responsive, or there are javascript errors reported in the error console.
* Choose **Optimized**, when you are using a **cache/minify plugin, CDN** or any other cache related solution. The cache plugijn will take care of the rest.
* Choose **Optimized asynchronous**, when you have a **minimalistic setup**, not really using many other plugins/scripts, and you don't have an effective minify/cache solution.


