> For the complete documentation index, see [llms.txt](https://documentation.ajaxsearchpro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ajaxsearchpro.com/compatibility-settings.md).

# Compatibility Settings

### What is Compatibility? <a href="#what-is-compatibility" id="what-is-compatibility"></a>

The **Compatibility** menu collects the settings used to make Ajax Search Pro work smoothly alongside your **theme, other plugins, and hosting environment**.

{% hint style="info" %}
**Most sites never need to touch these.** The defaults work for the vast majority of setups. Reach for Compatibility when something specific is wrong — the search box looks broken under your theme, the search stops working after AJAX page navigation, results are missing because of a database collation quirk, and so on. Change one setting at a time and test.
{% endhint %}

You'll find it under **Ajax Search Pro → Compatibility** in the WordPress admin menu, organised into four panels:

* **CSS & JS** — styling and front-end behaviour compatibility.
* **CSS & JS Loading** — how and where assets are delivered.
* **Query** — database/query character-set and validation tweaks.
* **Other** — REST API and meta-box integration.

<figure><img src="/files/uWxOAr7Rw2N6Ou55wN1d" alt=""><figcaption></figcaption></figure>

Each panel has a **Save** button and a shared **Reset to defaults** (see [Saving & resetting](http://localhost:63342/markdownPreview/1738519729/markdown-preview-index-u1lmqgqm875fjrdbdm4f3e7g0u.html#saving--resetting)).

***

### CSS & JS <a href="#css--js" id="css--js"></a>

Styling and front-end behaviour compatibility with your theme:

* **Prevent body scrolling on mobile when results are open** — stops the background page from scrolling while the results box is open on touch devices.
* **Detect AJAX powered themes** — enable if your theme loads pages via AJAX and the search stops working after navigating between pages.
* **CSS compatibility level** — **Low / Medium / Maximum**. Increase it if the search box styling conflicts with your theme (higher levels make the plugin's CSS more specific so it wins over theme styles).
* **Minify CSS output** — minimizes the generated CSS to reduce its size.
* **Load Google Fonts** — loads the Google Fonts used by the search themes; disable if you manage fonts yourself.
* **Use custom AJAX handler** — uses a custom AJAX handler that bypasses part of the WordPress loading process for faster responses. Faster, but may not work with some plugins or themes.

<figure><img src="/files/ASz3qrei6BbNgVTNHrOv" alt=""><figcaption></figcaption></figure>

***

### CSS & JS Loading <a href="#css--js-loading" id="css--js-loading"></a>

Controls **how and where** the search assets are delivered:

* **JavaScript source** — the front-end JavaScript bundle variant: **No jQuery (non-minified)** or **No jQuery (minified)**.
* **Script loading method** — **Classic / Optimized / Optimized + Async**. The optimized methods defer script loading for better page performance.
* **Initialize instances only when in viewport** — defers initializing a search instance until it scrolls into view (helps page load when search bars are far down the page).
* **CSS loading method** — how the generated stylesheet is delivered: **Optimized / Inline / File**.

<figure><img src="/files/xiHB5FSyfJwsOkoUHEXb" alt=""><figcaption></figcaption></figure>

#### Selective loading <a href="#selective-loading" id="selective-loading"></a>

By default the search assets load everywhere they might be needed. **Selective loading** lets you restrict them to specific pages.

{% hint style="warning" %}
**Not recommended.** Only use selective loading if you fully understand which pages your search instances actually appear on — restricting too aggressively will break the search where it's needed.
{% endhint %}

* **Enable selective loading** — turns the feature on (the options below are disabled until it is).
* **Load on the front page** / **Load on archive pages** — quick toggles for those page types.
* **Selective loading logic** — **Exclude on these pages** or **Include only on these pages**.
* **Pages / posts** — search for and pick the posts/pages the logic above applies to.

<figure><img src="/files/qhOuCD9Cg0ks2bYzupsM" alt=""><figcaption></figcaption></figure>

***

### Query <a href="#query" id="query"></a>

Database and query tweaks to work around character-set and collation issues. These mostly matter for **multibyte / accented languages** or unusual database configurations:

* **Soft query check** — uses a less strict query validation. Try this if results are unexpectedly missing.
* **Use ACF `get_field()`** — reads custom field values through ACF's `get_field()` function instead of direct database access (use when ACF formats or stores values in a way direct access misses).
* **Force database collation case** — **None / Force case sensitivity / Force case insensitivity** — to work around collation issues where searches match too much or too little.
* **Force UNICODE on queries** — forces the UNICODE charset on search queries; may help with multibyte languages.
* **Force UTF8 on LIKE queries** — forces the UTF8 charset on `LIKE` comparisons; may help with accented characters.

<figure><img src="/files/0CPY2JzgydoFLq5K05MD" alt=""><figcaption></figcaption></figure>

***

### Other <a href="#other" id="other"></a>

Integration toggles:

* **Enable the REST API endpoint** — exposes the search via the WordPress REST API (for headless or custom front-end integrations).
* **Display the Ajax Search Pro Meta Boxes on these post types** — choose which post types show the Ajax Search Pro meta boxes in the post editor.

<figure><img src="/files/5HSgOghNObao3JXAeY8r" alt=""><figcaption></figcaption></figure>

***

### Saving & resetting <a href="#saving--resetting" id="saving--resetting"></a>

* **Save** — stores the changes on the current panel.
* **Reset to defaults** — restores **all** compatibility settings (across every panel) back to their defaults. It asks for confirmation first.

***

### Tips & notes <a href="#tips--notes" id="tips--notes"></a>

* **Only change what you need.** These settings exist to fix specific conflicts — if your search works fine, leave them at their defaults.
* **Change one thing at a time.** When troubleshooting, adjust a single setting, save, and test before trying another, so you know what actually fixed (or broke) things.
* **Styling conflicts?** Try raising the **CSS compatibility level** first; **Maximum** makes the plugin's styles the most resistant to theme overrides.
* **Search breaks after navigation on an AJAX theme?** Enable **Detect AJAX powered themes**.
* **Missing results with accented/multibyte text?** Try the **Query** panel's UNICODE / UTF8 / soft query check options.
* **Avoid selective loading** unless you're certain which pages need the search assets.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.ajaxsearchpro.com/compatibility-settings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.