Cogio Search

Current version: 1.1.0

Introduction

Cogio Search is a WordPress plugin that adds an enhanced search box to a website. It improves the standard WordPress search experience by showing live search suggestions as a visitor types.

The plugin can be added to pages, posts, widgets, templates or other shortcode-supported areas using a simple shortcode. It is designed to be lightweight, flexible and easy to reuse across different websites. Each search box can be configured independently through shortcode options, including its alignment, preferred input width, wording and dropdown direction.

Cogio Search still uses the normal WordPress search results page as a fallback. This means that if JavaScript is unavailable, or if a visitor presses the search button instead of choosing a suggestion, the search form will continue to work as a standard WordPress search form.

Features

Cogio Search currently includes the following features:

• Search box shortcode
• Live search suggestions as the visitor types
• Search suggestions powered by a custom WordPress REST API endpoint
• Support for selected public post types, such as pages and posts
• Settings page under Settings > Cogio Search featuring:
  • Configurable number of suggestions
  • Configurable minimum character count before suggestions appear
  • Option to exclude specific pages or posts from suggestions
  • Configurable default placeholder text
• Per-shortcode alignment controls
• Per-shortcode search input width control
• Automatic dropdown positioning
• Optional manual dropdown direction control
• Keyboard navigation for suggestions
• “View all search results” link beneath suggestions
• Standard WordPress search fallback
• Contextual labels in suggestions:
  • Posts show their categories
  • Child pages show their parent page name
  • Top-level pages show no label

Guides

Adding a Search Box

To add a search box, place the following shortcode where you want the search form to appear:

[cogio_search]

This can be added to any area of the website that supports shortcodes, including:

• pages
• posts
• widget areas
• footer areas
• template parts, if shortcodes are processed

The default shortcode will display a left-aligned search box using the placeholder text set in the plugin settings.

Adding Search in a Theme Template

To add the search box directly inside a theme template file, use:

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

This can be useful if the search form needs to appear in a header, footer, sidebar or custom template.

Shortcode Options

The shortcode supports optional attributes. These allow each search box to be positioned and controlled independently.

Alignment

The align attribute controls the horizontal position of the search form and whether it uses the plugin’s standard maximum width or fills its container.

Left Aligned

[cogio_search align="left"]

This displays the search form aligned to the left.

This is also the default behaviour if no alignment is specified.

Centred

[cogio_search align="centre"]

This displays the search form centred within its container.

The plugin also accepts the alternative spelling:

[cogio_search align="center"]

Right Aligned

[cogio_search align="right"]

This displays the search form aligned to the right.

Full Width

[cogio_search align="full"]

This displays the search form at full width within its container. When align=”full” is used with min_width, the search form still occupies the full available width. The min_width value is treated as the preferred width of the input within that form.

This is useful for larger search areas, landing pages, hero sections or full-width footer layouts.

Search Input Width

The min_width attribute sets the preferred minimum width of the search input.

This value applies to the text input only. The Search button is displayed alongside the specified input width and is not included in the measurement.

Example:

[cogio_search min_width="500px"]

This asks the search input to use a width of 500 pixels when sufficient space is available.

The following CSS units are supported:

• px
• rem
• em
• ch
• vw
• %

For example, the width can be set using rem units:

[cogio_search min_width="30rem"]

The specified value acts as the input’s preferred minimum width rather than a fixed width. If the search form is placed inside a narrower container, the input can shrink to fit the available space and avoid horizontal overflow.

If min_width is not included, the search form uses its normal default sizing.

Dropdown Direction

The dropdown attribute controls whether the suggestion box opens upwards, downwards or automatically chooses the best direction.

Automatic Dropdown Positioning

[cogio_search dropdown="auto"]

This is the default behaviour.

When suggestions are displayed, the plugin checks the available screen space. If there is not enough space below the search form, the suggestions open upwards. If there is enough space below, they open downwards.

This helps prevent unwanted extra white space appearing at the bottom of a page when the search form is used in a footer.

Force Dropdown Downwards

[cogio_search dropdown="down"]

This forces the suggestions to open below the search form.

This may be useful for search forms placed in headers, hero sections or near the top of a page.

Force Dropdown Upwards

[cogio_search dropdown="up"]

This forces the suggestions to open above the search form.

This may be useful for search forms placed in footers or near the bottom of a page.

Combining Shortcode Options

Shortcode options can be combined to control the positioning, input width, wording and dropdown behaviour of each search form.

For example, a centred search form with automatic dropdown positioning:

[cogio_search align="centre" dropdown="auto"]

A full-width footer search form that always opens upwards:

[cogio_search align="full" dropdown="up"]

A right-aligned header search form that opens downwards:

[cogio_search align="right" dropdown="down"]

A centred search form with a preferred input width of 30 rem:

[cogio_search align="centre" min_width="30rem"]

A right-aligned header search form with a preferred input width of 500 pixels:

[cogio_search align="right" min_width="500px"]

A centred search form with a custom input width and automatic dropdown positioning:

[cogio_search align="centre" min_width="30rem" dropdown="auto"]

Custom Placeholder Text Per Search Box

The default placeholder text is set in the plugin settings, but it can also be changed for an individual shortcode.

Example:

[cogio_search placeholder="Search our website"]

This changes the text shown inside the search field before the visitor starts typing.

Custom Button Text Per Search Box

The search button text can also be changed per shortcode.

Example:

[cogio_search button_text="Go"]

This changes the button text from “Search” to “Go”.

Custom Accessible Label

The search field includes a hidden label for accessibility. This label can be changed using the label attribute.

Example:

[cogio_search label="Search the website"]

This label is not visually displayed, but it helps screen readers understand the purpose of the field.

Plugin Settings

The plugin settings can be found in the WordPress admin area under:

Settings > Cogio Search

The settings page controls the default behaviour of the search form and the live suggestions.

Post Types to Search

This setting controls which public post types are included in live search suggestions.

By default, the plugin searches:

• Pages
• Posts

Depending on the website, other public post types may also be available, such as products, case studies, team members or resources.

Only public published content is returned in search suggestions.

Number of Suggestions

This setting controls how many live suggestions are shown when a visitor types into the search box.

The recommended setting is usually 5 or 6.

A smaller number keeps the dropdown tidy. A larger number may be useful on content-heavy websites, but the dropdown can become harder to scan.

Minimum Characters Before Searching

This setting controls how many characters a visitor must type before suggestions are requested.

The recommended setting is usually 2 or 3.

A lower number makes suggestions appear sooner, but may return less useful results. A higher number reduces unnecessary searches and usually produces more relevant suggestions.

Excluded IDs

This setting allows specific pages or posts to be excluded from search suggestions.

Enter page or post IDs separated by commas.

Example:

12, 34, 56

This is useful for excluding pages that should not be promoted through live search, such as:

• thank-you pages
• hidden landing pages
• policy pages
• outdated content
• test pages

This only affects live suggestions. The standard WordPress search results page may still include those pages unless the theme or another plugin also excludes them from normal search.

Search Box Placeholder

This setting controls the default placeholder text used by the search form.

Example:

Search this website

This default can be overridden on individual shortcodes using the placeholder attribute.

How Search Suggestions Work

When a visitor starts typing, Cogio Search waits briefly before sending the search term to WordPress. This avoids sending a request for every single keystroke.

Once the minimum character count is reached, the plugin searches the selected post types and returns a short list of matching public results.

Each suggestion can include:

• the page or post title
• a contextual label
• a short excerpt
• a link to the result

Clicking a suggestion takes the visitor directly to that page or post.

Suggestion Labels

Cogio Search uses contextual labels to make suggestions more useful.

For posts, the plugin shows the post categories.

For child pages, the plugin shows the parent page name.

For top-level pages, no label is shown.

Examples:

A post may appear as:

Website maintenance tips WordPress Guides

A child page may appear as:

Hosting Support Website Hosting

A top-level page may appear simply as:

Contact

This avoids showing generic labels such as “Page” or “Post”, which are often less helpful to website visitors.

View All Search Results

The suggestion dropdown includes a “View all search results” link.

This allows visitors to go to the standard WordPress search results page for the term they have typed.

This is useful when the visitor wants to see more results than the live suggestion list provides.

Standard Search Fallback

The search form continues to work as a normal WordPress search form.

If a visitor types a search term and presses the search button, they will be taken to the standard WordPress search results page.

This means the search form remains usable even if:

• JavaScript is unavailable
• the visitor ignores the live suggestions
• no suggestion is selected
• the browser does not support the enhanced behaviour

Keyboard Support

The suggestion dropdown supports keyboard navigation.

Visitors can use:

• Down arrow to move through suggestions
• Up arrow to move backwards through suggestions
• Enter to open the selected suggestion
• Escape to close the suggestion dropdown

This makes the search form easier to use for keyboard users and improves accessibility.

Troubleshooting

Suggestions Are Not Appearing

Check the following:

1. The search term meets the minimum character setting.
2. The website has published content matching the search term.
3. The relevant post types are enabled in Settings > Cogio Search.
4. The page or post is not listed in the excluded IDs setting.
5. JavaScript is working on the website.
6. The browser console does not show any JavaScript or REST API errors.

The Search Button Looks Too Narrow

This issue was addressed in Cogio Search version 1.0.1. Make sure the plugin is running version 1.0.1 or later.

If the issue still appears, check whether the theme has button styles that are overriding the plugin CSS.

Suggestions Open in the Wrong Direction

By default, the plugin uses automatic dropdown positioning.

If a particular layout needs manual control, use the dropdown shortcode attribute.

Force suggestions upwards:

[cogio_search dropdown="up"]

Force suggestions downwards:

[cogio_search dropdown="down"]

The Search Input Is Too Wide or Too Narrow

The preferred width of an individual search input can be controlled using the min_width shortcode attribute.

Example:

[cogio_search min_width="500px"]

The value applies to the text input only. The Search button is displayed alongside it.

The specified width is responsive. If the search form is placed inside a container that is narrower than the requested width, the input will shrink to fit the available space.

If the input is not using the expected width, check:

• The min_width value includes a supported CSS unit.
• The shortcode uses an underscore: min_width.
• The parent theme container is wide enough to accommodate the requested input width and Search button.
• The theme is not applying conflicting width or flexbox rules to the form or input.
• The website and browser caches have been cleared after updating the plugin.
• Supported units are px, rem, em, ch, vw and %.

The Search Form Is Not Positioned Correctly

Use the align shortcode attribute.

Examples:

[cogio_search align="left"]
[cogio_search align="centre"]
[cogio_search align="right"]
[cogio_search align="full"]

Also check the width of the container the shortcode has been placed inside. The plugin can align the form within its available space, but it cannot make the parent container wider than the theme allows. The min_width attribute can set the preferred width of the search input, but the input will still shrink when the parent container does not provide enough space.

Changes Are Not Showing Immediately

The plugin uses short-lived caching for search suggestions.

If content, categories or page parents have just changed, the old suggestion data may appear briefly. This should clear automatically after a few minutes.

Browser caching or website caching plugins may also delay CSS and JavaScript changes from appearing immediately.