Skip to main content

In Page Search

The In Page Search block adds a lightweight client-side filter input to the page.

It is designed for situations where content is already rendered on the page and you want users to quickly narrow visible items without loading another page or using an external search service.

Typical use cases include:

  • staff or member directories
  • event or resource grids
  • card lists
  • grouped content where each item already exists in the DOM

What this block does​

This block renders a search field and filters existing page elements in place.

You provide:

  • a selector for the items to show or hide
  • a selector for the text inside each item that should be matched

As the user types, the block:

  1. reads the cached text for each matched item
  2. compares it against the current query
  3. hides non-matching items with the hidden attribute
  4. optionally shows helper UI such as a no-results message or a +X more link

The block builds its item index on page load so it does not need to rescan the DOM on every keystroke.

Required setup​

This block depends on valid CSS selectors.

Items To Filter Selector​

This selector identifies each result item that should be shown or hidden.

  • Example: .directory-card
  • Example: .event-listing
  • Example: li.team-member

Each matching element is treated as one searchable item.

Text Match Selector​

This selector identifies the text inside each item that should be searched.

  • Example: .directory-card__name
  • Example: .event-listing__title
  • Example: .staff-card h3

The selector is evaluated inside each matched item.

If this field is empty, the block falls back to using the full text content of the entire item.

Block settings​

Placeholder​

Optional placeholder text for the search field.

  • Default: Search

This only affects the input placeholder text. It does not change the search behavior.

Hash Query Variable​

Optional variable name used to pre-populate the search from the page URL hash.

  • Example variable name: directory-search

Example URLs:

  • #directory-search=smith
  • #?directory-search=smith
  • #directory?directory-search=smith

If this setting is populated, the block reads the configured variable from the hash and uses that value as the current search query.

If the hash changes after page load, the block updates the search field and re-runs the filter.

Off by default.

When enabled, the block still tries exact substring matching first, but it can also tolerate small typos for longer search terms.

Current tolerance:

  1. 3 characters or fewer: exact match only
  2. 4 to 7 characters: up to 1 edit
  3. 8 or more characters: up to 2 edits

This uses a bounded edit-distance check, which keeps the feature conservative enough for names and short labels without making very short searches too loose.

Show No Results Message​

Off by default.

When enabled, the block renders a message below the search input whenever:

  • the user has entered a non-empty query, and
  • zero items match that query

No Results Message​

Only shown when Show No Results Message is enabled.

  • Default: No results found.

Use this to customize the empty-state message for the current page.

Examples:

  • No people matched your search.
  • Try another keyword.

Off by default.

When enabled, the block can append a helper link after the filtered results when some items are hidden by the current search.

That link:

  • shows how many items are currently hidden
  • appears after the shared results container
  • clears the search when clicked
  • restores all results

+X More Link Text​

Only shown when Show +X More Link is enabled.

  • Default: +%count% more

Use %count% anywhere in the text where the hidden item count should appear.

Examples:

  • +%count% more
  • Show %count% more results
  • %count% more people

If the custom text does not contain %count%, the block falls back to the default template so the count is always visible.

How matching works​

Normal matching​

By default, the block performs a normalized substring search.

Normalization includes:

  • lowercasing
  • collapsing repeated whitespace
  • removing diacritics where supported by the browser

This means searches such as Jose can still match text like José.

Fuzzy matching​

If Fuzzy Search is enabled and an exact substring match fails, the block tokenizes the item text and compares each search term against those tokens using a small edit-distance threshold.

This is useful for minor typos such as:

  • Smth matching Smith
  • Jonhson matching Johnson
  • Andersn matching Anderson

It is not intended to behave like a full search engine or phonetic matcher.

Hash behavior​

If Hash Query Variable is configured, the block syncs with the URL hash in two ways.

Pre-populating from the hash​

On page load, the configured variable is read from the hash and used to seed the search field.

Clearing the hash when the search is cleared​

If the search is cleared:

  • with the native search input clear control
  • by deleting the search text manually
  • by clicking the +X more link

the block removes the configured variable from the hash.

If other hash query variables are present, the block attempts to preserve them.

How hidden results are handled​

Matching items remain visible. Non-matching items receive the hidden attribute and aria-hidden="true".

If all indexed items share the same parent element, the block adds this helper class to that parent:

yoko-in-page-search__results

The bundled CSS then forces hidden direct children of that container to remain hidden:

.yoko-in-page-search__results > [hidden] {
  display: none !important;
}

This is useful for themes or component styles that might otherwise override default hidden behavior.

When enabled, the +X more link is only added if the matched items share a single parent container.

That requirement exists because the link is appended after the filtered items inside that common parent.

When it appears​

The link appears only when:

  • the setting is enabled
  • the user has entered a non-empty query
  • one or more items are hidden by the current filter
  • all indexed items share one parent element

What happens on click​

Clicking the link:

  1. clears the current search
  2. restores all items
  3. removes the configured hash query variable, if one is set
  4. returns focus to the search input

The helper wrapper for this link is centered horizontally and vertically.

Example setup​

Example 1: Staff directory cards​

Rendered markup:

<div class="staff-grid">
  <article class="staff-card">
    <h3 class="staff-card__name">Jane Smith</h3>
  </article>
  <article class="staff-card">
    <h3 class="staff-card__name">John Anderson</h3>
  </article>
</div>

Block settings:

  • Items To Filter Selector: .staff-card
  • Text Match Selector: .staff-card__name
  • Placeholder: Search people
  • Hash Query Variable: directory-search
  • Fuzzy Search: on
  • Show No Results Message: on
  • No Results Message: No people matched your search.
  • Show +X More Link: on
  • +X More Link Text: +%count% more people

Example URL:

#directory-search=smth

With fuzzy search enabled, this may still match Smith.

Example 2: Event list using full item text​

If each item contains only the content you want searched, leave Text Match Selector empty.

Block settings:

  • Items To Filter Selector: .event-item
  • Text Match Selector: empty

In that case, the block searches the full text content of each .event-item.

Accessibility notes​

  • The block includes a screen-reader-only label for the search input.
  • Hidden items receive aria-hidden="true" when filtered out.
  • The no-results message uses aria-live="polite" when enabled.

As always, make sure the surrounding markup and visible labels make sense in the page context.

Troubleshooting​

Nothing happens when I type​

Usually this means one of the selectors does not match the frontend markup.

Check that:

  • Items To Filter Selector matches actual rendered elements on the page
  • Text Match Selector matches elements inside each item
  • the selectors are valid CSS selectors

Check that:

  • Show +X More Link is enabled
  • your search is actually hiding one or more items
  • all matched items share a single parent element

If items are spread across multiple parent containers, the link cannot be inserted as a single “after the results” element.

My hash value is not being read​

Check that:

  • Hash Query Variable exactly matches the variable name in the hash
  • the URL uses a query-style hash value such as #directory-search=smith or #?directory-search=smith
  • the block exists on the rendered page where that hash is being used

Fuzzy Search feels too broad or too narrow​

The fuzzy matcher is intentionally limited to minor typo tolerance.

It is best suited to short names and labels. If you need broader ranking, stemming, or relevance tuning, use a dedicated search integration instead of this block.

Technical notes (for developers)​

  • Block name: yoko-core/in-page-search
  • Rendered server-side via render.php
  • Frontend behavior is handled in view.js
  • The block indexes matching items once on page load for efficiency
  • Search text is normalized before comparison
  • Optional fuzzy matching uses a bounded Levenshtein-distance check
  • The block listens for hash changes when Hash Query Variable is configured
  • Clearing the query also clears the configured hash variable