Skip to main content
Skip to article
Search UX 2026-07-10 34 min read

Ecommerce Search Modal UX: When to Use It and How to Design It

An ecommerce search modal is worth its interruption only when product finding has become one focused job. The page behind it becomes inert, focus moves into a named search task, and the layer owns the query, suggestions, product evidence, recovery, and close or submit path. That behaviour, not a rounded panel or a dimmed background, is what makes it a modal.

The short answer

Use the middle surface: more room than a popup, less permanence than a results page.

The modal earns its layer when suggestions, decision-ready product evidence, and recovery need to arrive together. It is the wrong choice when two suggestions answer the query or when filters, sorting, and comparison have become the real job.

Choose a modal
The shopper needs one contained finding decision with evidence and a safe return.
Choose a popup
A few suggestions can answer the query while the current page remains useful.
Choose a results page
The shopper needs durable exploration: filters, sorting, paging, history, or comparison.

The extra room is useful because it lets the interface show a query while it is being formed, separate suggestions from products, surface the evidence that distinguishes close matches, and make the full-results handoff explicit. It is not permission to fill a larger box with more ambiguous tiles.

This guide follows one running query, “waterproof work boot”, from the first attention handoff to the final destination. Along the way, it explains the shopper psychology, the dialog and autocomplete boundary, every important state, the mobile keyboard problem, and the evidence that tells you whether the surface actually helped.

Search the catalogue

waterproof work boot

Refine the query

waterproof work boots men
insulated waterproof work boots

Matching products

Current query

Waterproof boot

Composite toe · In stock

Waterproof boot

Steel toe · In stock

Escape closes search

View all results

Illustrative modal layout: the scrim pauses the storefront, the named layer owns the search task, and the close or submit action explains how the shopper leaves it. It is not a capture of a specific storefront.

Background

Paused and inert while search is open.

Focus

Moved into one named search task.

Return

Close restores the paused context.

Modal at a glance

What the modal should add

A good modal is not a larger search field. It earns its layer by combining focus, evidence, and a reversible handoff in one coherent search task.

  1. 01Focus: give search the shopper’s attention while the page waits behind it.
  2. 02Evidence: put query language, product identity, price, and availability close enough to support a choice.
  3. 03Return: close, edit, or submit without losing the query or the page the shopper paused.

Chapter 1 · Understand the shopper job

Why does an ecommerce store need a search modal?

The format should follow the decision, not the other way around. An exact-product shopper needs an identifier, a recognisable result, and a direct handoff. A shopper who knows only the product family needs language, categories, and enough suggestions to form a better query. A shopper comparing products needs the page, filters, sorting, and context to remain available while they decide. These are different jobs even when they begin in the same header field.

A modal earns its interruption when it can bring the evidence and the next action into one focused place. It does not earn it merely by looking polished or occupying more space. If the shopper still has to return to the page to compare, re-enter the query after every state change, or guess whether a card is in stock, the larger surface has added effort without completing the job.

Known item

Resolve the code, product name, or distinctive attribute and make the purchase path obvious.

Uncertain intent

Help the shopper refine language without forcing them to understand the catalogue first.

Focused finding

Hold several credible candidates, recovery paths, and a full-results handoff together without making the shopper rebuild the query.

Responsive layout examples

Change the frame, preserve the task

Desktop, tablet, and mobile do not need identical geometry. They do need the same query, state, evidence, and escape path.

Acceptance rule: resize and rotate each frame while editing the same query. If content, focus, or recovery changes meaning, not just position, the responsive design has diverged.

Chapter 2 · Compare the search surfaces

Why modal search is different from inline, popup, and results-page search

These are four honest versions of the same “waterproof work boot” search. The words can stay constant while the surface changes what remains visible, who owns focus, how much evidence fits, and whether the shopper is still browsing the original page. The modal is the focused middle ground: more capable than a popup, but less durable than a results page.

Inline search

01

The page stays in charge

A small, low-risk query where the result can sit in normal flow.

Wins: Context stays visible and the route is simple.

Watch: Do not let the result push the content into an accidental jump.

Anchored popup

02

Suggestions stay beside the field

A few suggestions that answer the query without a new task layer.

Wins: Fast recognition with a clear relationship to the input.

Watch: Give the popup room to escape clipping and remain usable on narrow screens.

Modal dialog

03

The search task gets the room

Product cards, recovery, and a deliberate handoff need one focused layer.

Wins: Attention, space, and interaction can be coordinated.

Watch: Inert the page, contain focus, and restore the exact context on close.

Search page

04

Comparison becomes the task

Filters, sorting, counts, paging, and a URL the shopper can revisit.

Wins: The result state has room to persist and support exploration.

Watch: Keep the submitted query, empty state, and return path coherent.

Read the container, not the silhouette

A floating rectangle is not automatically a modal. The anchored popup above keeps the page available and follows the combobox contract. The modal illustration dims and disables the page, so it owes the shopper a dialog contract. A side panel or bottom sheet can be modal too, but only when its outside content is inert and focus is contained. Appearance suggests; behaviour decides.

Chapter 3 · Decide when to use the modal

When should you use an ecommerce search modal?

Every surface that puts a search field over the page asks the shopper a question. An anchored combobox asks "can I answer from beside the content you are already looking at?" A modal asks more: "treat search as the whole job now, and dismiss me when you are done." That extra weight has to buy something: real room for suggestions and products, and protection from the page that would otherwise compete for attention.

So the practical rule is asymmetrical. Choose the smallest surface that can complete the search job. If a compact list beside the field answers the same query, a modal is wasted interruption. If the catalogue search needs suggestions, product cards, and a clear next action all at once, a modal is the surface that lets every element earn its place.

The interrupt is not the problem in itself. The problem is paying the interrupt without getting the payoff: opening a heavy dialog to ask a question that two suggestions could have answered. Nielsen Norman Group's modal-and-nonmodal guidance (checked August 10, 2026) makes the same point about dialogs generally: an interrupt is acceptable when the moment genuinely needs a focused decision, and wasteful when it competes with the task the shopper came to the page for.

The psychology of a modal is the psychology of a handoff. The shopper is doing catalogue work, scanning, comparing, multitasking between recommendations and the collection, and the modal says "set that down for a second so we can decide what to show next." That is only fair if the handoff is fast, and only safe if it is reversible: close the layer and the page, its scroll position, and the shopper's focus come back unchanged. The modal's trust budget is exactly the speed of the handoff plus the certainty of the return. When a store pays for this, it is buying a committed moment, a few seconds where the shopper makes one decision instead of spreading attention across four competing elements.

For ecommerce specifically, that committed moment earns its price when the job is a product finding decision, not a content scan. Shoppers who already know the exact product, its size, or its SKU want an identifier, verifiable evidence (image, price, stock), and a path straight to purchase. Shoppers who are still deciding want the catalogue language and categories the layer can surface without a page navigation. A search modal is the storefront tool that keeps both, a scan bar for the confident and a browse menu for the undecided, inside one surface whose only job is finding a product.

Use a modal when

Search becomes one focused job

The shopper needs more than a few suggestions: product evidence, recovery, variants, or a clear handoff must share one attentive layer.

The page can pause safely and closing can restore the exact context.

Use inline search when

The page helps interpret the answer

The query is low commitment, the response can live in normal document flow, and keeping the current page visible reduces rather than increases effort.

Read the inline search guide

Use a results page when

Comparison becomes the task

The shopper needs filters, sorting, counts, paging, a durable URL, or room to compare several products over time.

Read the results-page guide

Focus

One job, fewer rivals

The inert page stops competing for taps and attention while the shopper forms or checks a product-finding decision.

Room

Evidence beside language

The layer can show completions, categories, product cards, recovery, and full submission without squeezing them into a tiny popup.

Continuity

A safe way back

Close, edit, or submit without losing the query, scroll position, focus target, or the page the shopper paused.

The value test

If the same shopper can complete the same decision with an anchored popup, the modal adds interruption without value. Choose the modal when the focused layer materially improves evidence, formulation, or handoff, not because a larger panel looks more premium.

Surface coverage

What each search surface provides, and what it gives up

provides partial does not provide
Search surface coverage matrix: capabilities provided by inline, anchored popup, modal, and dedicated-page search.
CapabilityInline searchAnchored comboboxpopupModal searchdialogDedicated searchpage
Original page context remains available Provides Provides Partial Does not provide
Room for query suggestions Partial Provides Provides Partial
Room for decision-ready product cards Partial Partial Provides Provides
Search owns the shopper’s attention Does not provide Partial Provides Provides
Persistent URL and history Partial Partial Partial Provides
Takeaway: choose by trade-off, not by silhouette. Inline and anchored search keep page context live; a modal buys containment and room; a dedicated page buys persistent exploration.

The attention handoff

The modal does not steal attention. It trades it for a committed decision.

Attention is not lost when the layer opens and closes correctly; it is borrowed and returned with the page intact.

Attention handoff between page and search modalThe shopper's attention moves from the page into the search layer, is committed to a product decision, and returns to the unchanged page. The handoff is only worthwhile when a focused decision follows.Before: page contextIn the modalAfter: same page returnsPage, scroll, focusare all on holdone product decision,with evidencesame page, same scroll,same focus restoredTrust = fast handoff in + certain page restore out
Takeaway: the generous part of a search modal is not the screen it covers. It is the page it returns. If closing does not restore context exactly, the handoff is a theft, not a trade.

Chapter 4 · Commit to the interaction model

The chosen surface determines focus, background, and history

The surface decision is not finished when the visual mock-up looks right. It becomes a real product contract only when the implementation agrees about what can still be touched, where focus lives, which region scrolls, and whether the query has a durable destination. A panel beneath a field may be an anchored combobox; a full-screen mobile layout may be either a popup or a modal. Appearance suggests the model, but behaviour decides it.

Use the matrix below as an engineering handoff: it translates the shopper job into the semantic and browser responsibilities the team must implement and test. The modal column is intentionally demanding because a larger layer buys attention by taking the page away for a moment.

Search surface decision table
ModeUse whenFocus modelBackgroundStrengthRisk
Inline searchThe page can preserve the input and results without covering other work.Normal document flowRemains interactiveSimple navigation, history, and accessibility modelMay not fit a compact header or cross-page global search.
Anchored combobox popupSuggestions fit beside the input and do not need a separate task environment.Combobox and listbox or grid patternUsually remains availableFast, contextual, and visually connected to the fieldCan clip, collide, or become too dense on small viewports.
Modal search dialogSearch needs a dedicated layer, substantial results, or a mobile-first task surface.Dialog lifecycle plus nested search interactionInert while modal is openMore room and a clear search taskFocus, scrolling, history, layering, and closing behaviour are more complex.
Dedicated search pageThe shopper needs filters, sorting, counts, paging, or persistent result exploration.Normal page navigationNot applicableStable URL, history, and room for full result controlsAdds navigation before the shopper sees any result.

This is the modal's place in the wider search-layout decision. Use the ecommerce search layout guide for the broader surface, density, filter, and mobile choice. If the response should stay in normal page flow, continue to the inline search guide before choosing a modal. Use the autocomplete guide when the popup's request, ranking, or active-option behaviour is the problem; and use the results-page guide when the task has become persistent comparison.

Do not add role="dialog" to an anchored autocomplete popup merely because it floats above the page. Use the combobox and popup pattern that matches its behaviour. Reserve modal semantics for a layer that actually makes outside content inert and contains the task.

The modal is a fit when

  • The search job ends in a product decision made from suggestions, cards, or a follow-up action.
  • The shopper would accept a committed moment because the query needs room or a level of focus the page cannot give.
  • The store can return the page exactly on close: the psychological promise that makes the interrupt fair.

Prefer the other formats when

  • Two suggestions beside the input answer the query: the anchored combobox keeps the page live.
  • The shopper is mid-comparison on a product page and needs the page itself to stay interactive.
  • The task ends in filters, sorting, paging, and persisted exploration: that is the search page's job.
  • Ask "what is the one job after an interrupt?" If there is no single next decision, there is no payoff.

Chapter 6 · Separate the dialog and autocomplete contracts

The modal shell and the autocomplete own different state spaces

The shell owns whether search is open and modal. Autocomplete owns the current query response and active option. Keeping these responsibilities separate prevents a request failure from closing the dialog, and prevents an Escape key from clearing more state than intended.

The WAI-ARIA combobox pattern explicitly allows the popup to be a dialog as well as a listbox, grid, or tree. When the popup is a dialog, focus moves into the dialog and the modal dialog keyboard interaction applies, instead of tracking the active option with aria-activedescendant. That is the structure a search modal needs: the input keeps its combobox behaviour, and the shell owns the dialog contract once focus enters the layer.

Trigger

Owns

Open action, accessible name, shortcut hint, and return-focus target

Does not own

The live query or suggestion selection after the dialog opens

Dialog shell

Owns

Modal semantics, accessible name, initial focus, focus containment, close action

Does not own

Autocomplete ranking, result identity, or query-submission rules

Search form

Owns

Current query, clear, submit, input label, and committed search navigation

Does not own

Background inertness or focus restoration

Suggestion surface

Owns

Current response, groups, active option, selection, loading, empty, error states

Does not own

Whether the surrounding layer is modal

Background controller

Owns

Inert state, visual scrim, page-scroll preservation, outside-interaction policy

Does not own

Clearing the search query as a side effect of closing

Navigation and analytics

Owns

Destination, URL, history, event trace, and outcome linkage

Does not own

Visual highlight or keyboard focus inside the dialog

The classic misdiagnosis is a report that "search is slow" when the dialog shell opens fast but the suggestion request hangs. Separate the shells: instrument the shell open and the suggestion request as different boundaries, then the fix has an owner.

Chapter 7 · Define the dialog states

Opening and closing are states, not animation details

The page should not remain interactive while a modal is visually open, and focus should not move into a shell that is not ready. Model opening and closing explicitly so focus, inertness, scroll, animation, and query state transition together.

State machine

The modal life cycle as transitions

Every arrow is a transition that must hand focus and state correctly. A "flicker" you attribute to CSS is often a broken state transition.

Search modal state machineThe dialog moves from closed through opening, idle, querying, results, and closing, with a separate no-suggestions branch that can return to querying.Closedpage + triggerOpeningshell + input readyOpen · idleinput, no query yetOpen · queryingrequest in flightOpen · resultsgroups + full-results pathClosinginert removed, focus restoredNo useful suggestionsexplain, correct, recoveropen / shortcutready + focus settypingresponse arrivesno useful responseedit query (returns)Escape · closerestore scroll + focusSubmitting from any open state navigates to the full results page.
Takeaway: test the transitions, not just the screens. A modal that "flashes" is usually a transition that did not wait for the shell to be ready.
Search dialog state contract
StateVisible contentFocusTransition
ClosedPage and search triggerNormal page focusTrigger, documented shortcut, or route state opens search
OpeningDialog shell and input become availableMoves to the search input or another deliberate initial elementInitial focus and background inertness complete before interaction
Open, idleInput plus deliberate recent, popular, or category content, or no body contentQuery inputTyping, selecting idle content, clear, submit, or close
Open, queryingCurrent query and stable loading treatmentInput, with the autocomplete active option managed separatelyCurrent response, error, clear, submit, or close
Open, resultsGrouped current suggestions and full-results pathInput or a dialog descendant according to the popup patternSelect, edit, submit, clear, or close
Open, no useful suggestionsQuery, explanation, reformulation or category recovery, and full submitInput or the explicit recovery actionEdit, submit, select recovery, clear, or close
ClosingDialog removed and background restoredReturns to the invoking control or a logical continuation targetClosed with scroll and page state restored

State showcase

The same dialog, four states. One stable shell across two form factors.

Across both forms, the query row and close or back action stay stable. Idle invites, querying builds trust, results support choice, and no suggestions provides recovery.

Stable shell

Query, close or back, focus target

Changing body

Prompt, progress, evidence, recovery

Design test

Same state contract on every viewport

Desktop

Centred window

The page is visible but inert; the window owns attention and its own result scroll.

Idle
Orient

Useful starting points: Recent, popular, or category paths, only when the source is honest.

Querying
Wait

Current query + progress: Keep the typed words visible and make the wait feel owned by the dialog.

Results
Decide

Evidence, not decoration: Show the attributes, price, and availability that separate close matches.

No suggestions
Recover

Explain the miss + next move: Offer reformulation, a browse path, or full-catalogue search.

Mobile

Full-viewport layer

The layer uses the visual viewport; the header and query stay reachable above the keyboard.

Idle
Orient

Useful starting points: Recent, popular, or category paths, only when the source is honest.

Querying
Wait

Current query + progress: Keep the typed words visible and make the wait feel owned by the dialog.

Results
Decide

Evidence, not decoration: Show the attributes, price, and availability that separate close matches.

No suggestions
Recover

Explain the miss + next move: Offer reformulation, a browse path, or full-catalogue search.

Takeaway: the form factor changes the container, not the contract. If mobile and desktop disagree about what idle, querying, results, or recovery means, the state model is the bug, not the viewport.

The most common state bug is a loop. "Open" fires from "Closed" while "Closing" sets a flag that "Opening" reads a tick behind. On slow networks this shows up as a modal that never fully appears or never fully closes. Model both transitions and verify them at throttled speed.

Chapter 8 · Design the idle state

Show idle content only when its source and job are honest

The empty dialog does not need to become a promotional homepage. Idle content should help the current shopper resume a task, learn catalogue language, or open a stable browse path.

If the store cannot support recent or popular searches with real data and an appropriate privacy policy, leave the body quiet. A focused input is a complete idle state.

Idle content is a recognition aid, not a second navigation system. A short labelled set lets shoppers recognise a familiar query or category; a wall of links creates choice overload and asks them to browse the whole catalogue before they have even decided to search. Keep one reason for each group, make the source visible, and remove the group when its source is empty.

Recent searches

Help the same shopper resume a real task.

Requires: Clear source, privacy behaviour, and a way to remove history.

Avoid: Inventing recent items from global popularity.

Popular searches

Expose common catalogue language when the current context supports it.

Requires: A measured source, current period, and a label that says these are popular.

Avoid: Treating popularity as personalisation or relevance to this shopper.

Category shortcuts

Offer stable, high-level browse paths before the shopper has formed a query.

Requires: A small editorial set with clear category names.

Avoid: Recreating the full navigation menu inside search.

No idle body

Keep the task focused when there is no honest or useful idle content.

Requires: Input, label, close action, and empty space still feel intentional.

Avoid: Filling space because the dialog looks unfinished.

Idle state

An honest idle layout: recent, popular, then one clear away

Every entry names its source. None of it pretends to be a personal match for this shopper.

Desktop modal in the idle stateA centred modal shows a search input, a section of recent searches for this shopper, a labelled section of popular searches, and a compact set of category shortcuts. Background content is dimmed and inert.Recent searchesPopular this weekCategoriesBootsRain gearWorkwear
Takeaway: every block is labelled by its real source: "recent" and "popular" are distinct, and clearing history removes the recent section, not the catalogue.

Chapter 9 · Manage focus and inertness

A modal search task needs a complete focus life cycle

The WAI-ARIA modal dialog pattern requires focus to move inside on open, Tab and Shift+Tab to stay within the dialog, and Escape to close. It also recommends a visible close control and a dialog name through a visible label or accessible label.

As checked on August 10, 2026, the APG guidance also notes that initial focus depends on content. For a search task, the input is commonly the useful initial target, but a large structured dialog may need focus at a static heading so the content is understood before interaction.

A custom shell must build that contract by hand, but the native dialog element supplies its core. Opened with showModal(), the browser renders the dialog in the top layer, makes everything outside it inert, keeps Tab inside it, closes on Escape, returns focus to the invoking element, and exposes the dialog with an implicit aria-modal="true". The dimmed background is styled with the ::backdrop pseudo-element. What the browser still leaves to the page is the search-specific work: the virtual keyboard, the combobox popup behaviour inside the dialog, and the abort-and-update request handling.

Before open

Record the invoking element and current scroll position.

Verify: The trigger is still connected or a fallback return target is defined.

On open

Make the background inert and move focus inside the dialog.

Verify: Keyboard and screen-reader users enter one named search task.

While open

Contain Tab and Shift+Tab within the modal dialog.

Verify: Focus cannot reach the obscured background controls.

Inside autocomplete

Apply the chosen combobox or dialog-popup pattern consistently.

Verify: Input focus, active option, visual highlight, and selected value agree.

On close

Remove inertness, restore page scroll, and return focus.

Verify: The shopper returns to the trigger or a logical continuation location.

If the team needs the broader keyboard, screen-reader, naming, and touch review, continue with ecommerce search accessibility guide.

Chapter 10 · Compose the result hierarchy

Use the extra space to clarify the search path

A modal can hold more than an anchored dropdown, but more space does not justify more noise. Preserve resource labels, keep direct product matches distinct from query and category paths, and expose the current query in the full-results action.

The exact order depends on query intent. An exact SKU or product title can outrank a query completion. A policy query may deserve an article above products. Build the hierarchy from intent and evidence, not one fixed group sequence.

Correction

Query completion or spelling correction

It makes the typed intent clearer or produces a better full result path.

Text, match emphasis, and a query action

High confidence

Exact product or variant

Evidence supports direct navigation.

Title, relevant identifier or attribute, price and availability when reliable

Browse path

Collection or category

The query describes a product family or a broader mission.

Clear resource label and destination

Informational

Page or article

The query asks a policy, guide, or informational question.

Content label, title, and concise context

Escape path

View all results for the current query

The query can be submitted, including when prediction is empty.

The exact submitted query and a predictable action

Copy is part of the interaction

Use words that remove uncertainty before adding another control

Recognition is cheaper than recall. A label tells the shopper what a row is, what will happen next, and whether the result is a match or a recovery suggestion. Good microcopy therefore reduces the number of controls the layout needs to explain itself.

Microcopy examples for the same search task
JobPreferWhy it teaches
Name the taskSearch products, brands, and collectionsSets scope before the shopper types; the field is not asking them to guess what is indexed.
Label a suggestionCollection · Waterproof work bootsLets the shopper recognise the destination instead of decoding an unlabelled list.
Keep submission visibleView all results for “waterproof work boot”Preserves agency when prediction is incomplete or the exact query needs a full page.
Explain an empty responseNo suggestions yet: search the full catalogue or refine the querySeparates a predictive limitation from a claim that the catalogue is empty.

The ecommerce autocomplete guide covers request cancellation, candidate groups, ranking, active-option behaviour, and event design inside this shell.

Chapter 11 · Handle no suggestions without faking a result

An empty suggestion state is real, not a bug to hide

The absence of predictive suggestions does not prove that full search has no results. The surfaces may use different fields, resources, prefix behaviour, ranking, or limits. Preserve full submission for the current query.

Offer spelling, category, or substitute recovery only when the relationship is supported. Label recovery content so shoppers can distinguish it from a match.

No suggestions for

“waterprooof work boot”

Submit

Search the full catalogue for the typed query.

Correct

Suggest "waterproof work boot" when the correction is credible.

Recover

Offer a labelled category or adjacent path when it is supported and honest.

Mobile layer showing no useful suggestionsA full-viewport mobile search layer keeps the query in the input, states that there is nothing useful to suggest, and offers three honest actions: search the full catalogue, apply a spelling correction, or open a labelled nearby category.No suggestions for“waterprooof work boot”Did you meanBrowse insteadKeyboard occupies the space below
Illustrative mobile diagram, not a captured storefront state: keep the typed query visible, name the empty suggestion state, and label submit, correction, and browse recovery as separate paths.

On a mobile layer the same rules hold, but the real estate is vertical. The input, the "no suggestions" explanation, and the recovery paths all have to fit in the space the virtual keyboard leaves behind.

Note what is not shown: no fake product, no invented "we think you mean" that the catalogue cannot support, and no implicit claim that the submitted page will be empty. Submit, correct, and recover are each labelled actions, not rivals.

If the submitted page is also empty, continue with the zero-results recovery guide to design the full-page response.

Chapter 12 · Design mobile modal search

On a phone, preserve the search task before you preserve the desktop layout

When the virtual keyboard opens, the visible area can become much shorter than the CSS layout viewport. A fixed-height desktop dialog can leave the input or the active result behind the keyboard.

Use a layout that reserves a stable input region and gives the result body the remaining internal scroll area. Test on supported mobile browsers with the real keyboard, safe areas, address-bar changes, resize, and orientation.

Mobile modal contract

A mobile modal should read as four reachable zones. Keep the header and query anchored, let the result body own its scroll, and keep the next action above the keyboard. The exact height changes with the device, but the ownership of each zone should not.

01 · Header

Close stays reachable

Keep close or back in the safe area, away from the result scroll.

02 · Query

Input remains anchored

Keep the typed query and clear action visible while the keyboard is open.

03 · Results

List owns the scroll

Scroll the suggestions or products without moving the page behind the modal.

04 · Handoff

Next action stays clear

Place full results or product actions where a thumb can reach them above the keyboard.

The resize contract is documented, not guessed. Since Chrome 108 (November 2022), the on-screen keyboard on Android resizes only the visual viewport by default, so CSS viewport units such as dvh keep their pre-keyboard size unless the page opts into a different behaviour through the viewport meta tag: interactive-widget=resizes-content resizes both the layout and visual viewports, resizes-visual (default) resizes only the visual viewport, and overlays-content resizes neither. A search layer sized in viewport units needs the first option to stay above the keyboard; the behaviour also differs across browser and OS combinations, so verify it with the real keyboard on each target. Chrome's viewport resize walkthrough (checked August 10, 2026) shows the three behaviours on camera.

For the broader phone experience around search, not only the modal, continue with the mobile ecommerce search guide.

Keyboard before / after

A fixed-height dialog loses to the keyboard; a visual-viewport dialog survives it

Same store, same query, same phone. The difference is which viewport the dialog sizes itself to.

Before Fixed-height dialog
waterproof work boot
Waterproof work boots
Insulated work boots
Wide-fit work boots
Rows hidden
Keyboard covers the result list

The dialog keeps a desktop-sized body, so the keyboard covers part of the answer.

After Visual-viewport dialog
waterproof work boot
Waterproof work boots
Insulated work boots
Wide-fit work boots
Usable viewport
Keyboard stays below the response

The input stays anchored and the response gets the space above the keyboard.

Takeaway: size the dialog against the visual viewport available above the keyboard, keep the input anchored, and let the suggestion list own the internal scroll.
The dialog uses the visual viewport available above the virtual keyboard.
The input, clear action, and close action remain visible and distinct.
The suggestion list owns the internal scroll instead of moving the background page.
The current query survives keyboard open, close, resize, and orientation change.
Safe-area padding prevents controls from colliding with device edges.
Browser autocomplete and mobile OS autocorrect are disabled so their overlays cannot cover the layer.
The first useful suggestion appears without an oversized decorative header.
Touch selection does not trigger an adjacent row or background element.
Closing restores the page to the same scroll and focus context.

Scroll ownership

The list scrolls; the phone does not

The same mobile results across three interactions. None of them should move the page behind the layer.

Mobile modal owning its internal scrollThree phone-sized panels show the same suggestion list at different scroll positions. The input, close action, and full-results action stay fixed while the list body moves; the background page never scrolls.List at startactive optionActive option travels with focusList end, input still pinned
Takeaway: the page behind the modal never scrolls. The list, the input, and the full-results action all stay inside the layer, and the active option stays visible as the list moves.

Chapter 13 · Measure each latency boundary

Opening, prediction, rendering, and navigation are separate waits

Measure the search task in stages. A fast predictive endpoint does not compensate for a delayed dialog bundle, slow focus work, unstable image layout, or a sluggish destination page. Set budgets from your own store and audience rather than a universal threshold.

Latency boundaries to instrument
LayerStartEndInspect
OpenTrigger activationNamed dialog and focused input are readyBundle, hydration, focus work, scroll lock, animation
QueryEligible input changeCurrent request startsDebounce, composition, main-thread work, cache lookup
ResponseRequest startsCurrent response arrivesNetwork, retrieval, ranking, payload, stale cancellation
RenderCurrent response arrivesStable suggestions are visible and operableParsing, DOM, images, layout, announcement, active option
CommitSelection or submitDestination or results state is usableDestination URL, navigation, data fetch, history, focus

Worked boundary example

Use a measured result here only when the source, method, sample, date range, query mix, and measurement grain are recorded beside it. A retrieval or ranking time is one layer of the path; it does not prove that the modal opens, paints, announces, or navigates quickly. For a reader-run test, record the time from trigger to usable dialog, input to current response, response to stable presentation, and selection to usable destination, then report distributions rather than one unscoped average.

Report distributions by device, connection, query family, cache state, and response size, not a single average. An average hides the slow tail that matters on mobile search.

Chapter 14 · Measure the search task, not the events

Connect open, suggestion, submit, and the destination that finishes the task

Counting opens is not measuring search. The useful metric is a trace that spans the whole search task: opening the layer, resolving the query, choosing a suggestion, submitting, arriving at a destination, and then the outcome on that page. An expansion test overstates conversion if it counts opens that never lead to a results page, or clicks that never add to cart.

Outcome trace

From open to purchase, one connected search task

Each stage records its own events; the trace is what proves a shopper finished a job.

Search task outcome traceFive connected stages from opening the modal through resolving, selecting, submitting, and completing on the destination page, with an abandoned branch when a shopper drops out before selection.Opensearch_modal_opensearch_modal_readyResolvepredictive_requestpredictive_responseSelectsuggestion_impressionsuggestion_selectSubmitfull_search_submitCompletedestination_navigatedresult_outcomeAbandonedno select, no submit, no outcome

search_modal_open → search_modal_ready → predictive_response → suggestion_select → /products/waterproof-boot → add_to_cart

Example event flow for one session. Event names are suggestions, not a fixed schema; instrument the fields your analytics surface supports.

Takeaway: every stage is a separate instrumented boundary, and the trace, not the individual event, is what turns UI telemetry into a search-task outcome.

The search analytics guide defines the shared event and funnel vocabulary for the results page. For the full journey from query to checkout, including attribution across surfaces, continue with the revenue attribution guide.

Chapter 15 · Prove the modal’s promises

Test shell, autocomplete, mobile viewport, and outcome path separately

The modal can look polished while one of its hidden contracts is broken: the dialog shell, the predictive response, the mobile viewport, or the destination handoff. This final pass is not a substitute for the design decisions above. It converts them into evidence that names which layer owns a failure.

Use one page, one trigger, and one known query. Preserve that context while moving through the steps. If the shell fails, fix focus and dialog behaviour first; if suggestions diverge, inspect request state and ranking; if the selected product changes at the destination, inspect the product or variant handoff.

Promise 01

Containment

The page pauses, focus enters one named task, and the result body, not the obscured page, owns scrolling.

Promise 02

Current intent

The typed query stays visible and every suggestion, empty response, and submit action refers to that same query.

Promise 03

Useful handoff

Close restores the page, while select or submit reaches the intended product or results destination with its context intact.

  1. 1

    Classify the surface

    Decide whether the current experience is inline, an anchored combobox popup, a modal dialog, or a search page.

    Output: One declared interaction and accessibility model.

  2. 2

    Walk the state machine

    Test closed, opening, idle, querying, results, no suggestions, error, submit, and closing.

    Output: A state and transition defect list.

  3. 3

    Verify focus and background behaviour

    Open with keyboard, traverse forward and backward, use Escape, close visibly, and inspect focus return.

    Output: Evidence that the modal is contained without trapping the user.

  4. 4

    Exercise autocomplete separately

    Test stale responses, arrow keys, Enter, editing, clear, submit, and the destination.

    Output: Autocomplete defects separated from dialog-shell defects.

  5. 5

    Repeat with the virtual keyboard

    Check the visual viewport, internal scrolling, safe areas, resize, orientation, and background movement.

    Output: A mobile-specific repair list.

  6. 6

    Throttle and fail the data path

    Test slow open, slow response, reversed responses, empty response, and request failure.

    Output: A resilient fallback and current-query ownership check.

  7. 7

    Connect the outcome trace

    Trace open, ready, request, response, select or submit, destination, and checkout on one device.

    Output: One connected search-task outcome, not disconnected UI events.

The verification pass is complete when it identifies the failing owner and a repeatable test. "Search modal is broken" is not actionable by itself. "Closing with Escape restores focus, but a reversed predictive response replaces the current query's active option" is.

Frequently asked questions

Search modal questions, answered carefully

When should the search surface stay non-modal on mobile? +

When the trade-off is wrong for the task. If a handful of suggestions beside the input answers the query, an anchored combobox keeps the page visible. If the mobile search needs the full remaining height for suggestions and products, a full-viewport search layer is a variation inside the modal family. The clause that fails is "the outside page still reacts to taps".

Do I still need Escape when the layer is full-screen on mobile? +

Yes. The mobile keyboard may not deliver an Escape key. Provide the explicit close control, support the back gesture where the browser allows it, and keep Escape wired for the desktop case. Back-button behaviour varies by browser; test it on the target devices.

Should we build the shell on the native dialog element or a custom layer? +

Prefer the native dialog element with showModal() when the design allows it: the browser supplies the top layer, the inert background, focus containment, Escape, and focus return. Choose a custom shell when the design needs rendering or stacking the native element does not support, and then reproduce the full APG modal dialog contract. Either way, the search-specific behaviour, including combobox state, request handling, and the virtual keyboard, remains the product's responsibility.

Can the modal reuse the same catalogue as the results page? +

It should. If the modal's suggestion layer and the submitted results page run on different index contracts, "no suggestions" can be a surface-specific false negative. The two surfaces sharing the same eligible catalogue, query policy, and product identity is what keeps the predictive and full results paths coherent.

The modal should simplify search, not add a second source of truth

Let the dialog shell own the modal life cycle and let autocomplete own the current suggestion state. Keep full search available, preserve the current query, and restore page context when the shopper leaves the layer. Anything that shares state across those boundaries deserves its own acceptance test.

ParticleSearch is a fit when the store wants this to be a product responsibility rather than a permanent theme project. Its search modal owns the open, close, focus, query, result, and submission path while using the same catalogue and search behaviour as the full results page. A merchant can choose a compact, recommended, or expanded starting layout, set the number of product results, place suggestions above the results or in a side panel, and choose comfortable or compact spacing.

The important outcome is consistency. An exact identifier, a broad discovery query, a suggestion selection, and an Enter submission do not need separate theme implementations with different product evidence. After a verified launch, the merchant should not have to maintain focus trapping, body locking, mobile overlay behaviour, stale-request protection, and the modal-to-results handoff as unrelated fixes. ParticleSearch owns that search surface; the merchant still chooses its placement, presentation, and catalogue policy.

The boundary stays explicit. ParticleSearch does not repair a mislabelled catalogue, choose the layout for you, or guarantee that an open modal raises conversion. The merchant still verifies the result with the proof pass above, and with the storefront acceptance guide for the buyer experience after the layer opens.

The standard to ship against

A search modal is ready when the chosen surface matches the job, the current query survives every transition, the background and focus restore cleanly, the keyboard leaves the task usable, and one trace can connect open to destination. If one of those promises is unverified, the visual polish is not finished product quality.

One result contract

The modal and full page use the same eligible catalogue, query policy, and product identity.

Merchant-controlled shape

Presets coordinate the surface, then layout and product-card controls can be tuned and previewed.

Honest boundary

The theme still provides the trigger and visual context. ParticleSearch owns the search interaction after opening.