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
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.
- 01Focus: give search the shopper’s attention while the page waits behind it.
- 02Evidence: put query language, product identity, price, and availability close enough to support a choice.
- 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.
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
01The 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
02Suggestions 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
03The 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
04Comparison 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 guideUse 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 guideFocus
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
| Capability | Inline search | Anchored comboboxpopup | Modal searchdialog | Dedicated 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 |
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.
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.
| Mode | Use when | Focus model | Background | Strength | Risk |
|---|---|---|---|---|---|
| Inline search | The page can preserve the input and results without covering other work. | Normal document flow | Remains interactive | Simple navigation, history, and accessibility model | May not fit a compact header or cross-page global search. |
| Anchored combobox popup | Suggestions fit beside the input and do not need a separate task environment. | Combobox and listbox or grid pattern | Usually remains available | Fast, contextual, and visually connected to the field | Can clip, collide, or become too dense on small viewports. |
| Modal search dialog | Search needs a dedicated layer, substantial results, or a mobile-first task surface. | Dialog lifecycle plus nested search interaction | Inert while modal is open | More room and a clear search task | Focus, scrolling, history, layering, and closing behaviour are more complex. |
| Dedicated search page | The shopper needs filters, sorting, counts, paging, or persistent result exploration. | Normal page navigation | Not applicable | Stable URL, history, and room for full result controls | Adds 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 5 · Use the modal
How to use a search modal: frame the task, then preserve the return
Once the decision is made, use the modal as a complete task rather than a decorative container. Name the trigger, open one labelled dialog, move focus into the input, keep query and close controls reachable, show evidence that supports the next choice, and make both submission and return predictable.
A modal can be centred, edge-aligned, full-screen, or sheet-shaped. Those visual choices change density and reach, not the responsibilities. Every version still needs a named task, a visible close path, an inert outside, contained focus, a usable scroll region, and a predictable return.
- 01
Open
Name the search action and record where focus should return.
- 02
Contain
Pause the background and move keyboard and assistive focus inside.
- 03
Help
Keep the query, suggestions, states, and recovery path understandable.
- 04
Commit
Make selection, full search, and the destination explicit before action.
- 05
Return
Close without losing the page, scroll position, query, or focus target.
Desktop
Centred window
A contained search task over a page the shopper may want to return to.
Visual anatomy: Scrim + named dialog + pinned input + scrollable body
Trade-off: Most familiar, but the background must become truly inert.
Mobile
Full-viewport layer
The keyboard and result list need every usable pixel of the visual viewport.
Visual anatomy: Safe-area header + pinned input + internal result scroll
Trade-off: More room, but close, back, and keyboard behaviour must be obvious.
Wide desktop
Side panel
Search should feel like a secondary workbench while the page remains a reference.
Visual anatomy: Scrim + edge panel + fixed query controls + result groups
Trade-off: The edge can feel lighter, but it is still modal if the page cannot be used.
Touch context
Bottom sheet
A short search or recovery task benefits from a reachable lower control surface.
Visual anatomy: Drag-safe header + query row + bounded body + explicit close
Trade-off: Reachable and compact, but easy to confuse with a non-modal drawer.
| Visual choice | It changes | It does not change |
|---|---|---|
| Centred or side-aligned | Reach, density, and relationship to the page | The need for inertness, focus containment, and return focus |
| Window or full-screen | How much visual viewport the task occupies | The need for a name, close action, Escape, and a recovery path |
| Sheet or panel | Where the thumb and eye enter the task | Whether outside content can be interacted with |
Modal anatomy
A good layer is a chain of responsibilities
The visual shell is only one link. Show the whole handoff in a review so no team mistakes a scrim or animation for the modal contract.
01 · Trigger
Record the invoker and name the action.
02 · Inert
Pause background interaction and scroll.
03 · Dialog
Move focus into one named task.
04 · Evidence
Keep query, results, recovery, and submit visible.
05 · Return
Restore focus, scroll, and the query decision.
Comparison board
Six decisions where the stronger visual is also the clearer contract
Use these pairs in critique. The “weak” side is not a colour preference; it is a failure mode that creates extra interpretation or repair work.
Surface semantics
Floating, but still interactive
The panel floats over the page while background links and scroll still respond.
Modal, so the page is inert
A scrim, contained focus, and an explicit close action make the handoff legible.
Lesson: If the page remains available, teach a combobox. If it is blocked, fulfil the dialog contract.
Query commitment
View all
The action gives no clue which query or destination will be used.
View all results for “waterproof work boot”
The action repeats the current query and makes the handoff predictable.
Lesson: Copy is part of the interaction model; a label can prevent a second confirmation step.
Empty prediction
No results
A predictive miss is presented as proof that the full catalogue is empty.
No suggestions yet · Search the full catalogue
The UI names the limitation and preserves a direct recovery path.
Lesson: Do not turn a missing suggestion into a false product claim.
Scroll ownership
The page moves behind the layer
A swipe over the result list moves the obscured page and loses the search context.
The result body scrolls
The input and close action stay pinned while only the result region moves.
Lesson: Every scrollable region needs one obvious owner, especially above a mobile keyboard.
Focus return
Close and disappear
The layer closes, but keyboard focus lands at the top of the document or nowhere useful.
Close and return
Focus returns to the invoking search control or a declared continuation target.
Lesson: A reversible visual handoff needs a reversible focus handoff too.
Result evidence
Product-shaped boxes
Cards show a title but no identifier, attribute, price, or availability signal.
Decision-ready card
The card exposes the evidence that lets the shopper distinguish close matches.
Lesson: Use extra modal space for certainty, not a larger pile of ambiguous tiles.
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.
| State | Visible content | Focus | Transition |
|---|---|---|---|
| Closed | Page and search trigger | Normal page focus | Trigger, documented shortcut, or route state opens search |
| Opening | Dialog shell and input become available | Moves to the search input or another deliberate initial element | Initial focus and background inertness complete before interaction |
| Open, idle | Input plus deliberate recent, popular, or category content, or no body content | Query input | Typing, selecting idle content, clear, submit, or close |
| Open, querying | Current query and stable loading treatment | Input, with the autocomplete active option managed separately | Current response, error, clear, submit, or close |
| Open, results | Grouped current suggestions and full-results path | Input or a dialog descendant according to the popup pattern | Select, edit, submit, clear, or close |
| Open, no useful suggestions | Query, explanation, reformulation or category recovery, and full submit | Input or the explicit recovery action | Edit, submit, select recovery, clear, or close |
| Closing | Dialog removed and background restored | Returns to the invoking control or a logical continuation target | Closed 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
OrientUseful starting points: Recent, popular, or category paths, only when the source is honest.
Querying
WaitCurrent query + progress: Keep the typed words visible and make the wait feel owned by the dialog.
Results
DecideEvidence, not decoration: Show the attributes, price, and availability that separate close matches.
No suggestions
RecoverExplain 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
OrientUseful starting points: Recent, popular, or category paths, only when the source is honest.
Querying
WaitCurrent query + progress: Keep the typed words visible and make the wait feel owned by the dialog.
Results
DecideEvidence, not decoration: Show the attributes, price, and availability that separate close matches.
No suggestions
RecoverExplain the miss + next move: Offer reformulation, a browse path, or full-catalogue search.
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.
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.
| Job | Prefer | Why it teaches |
|---|---|---|
| Name the task | Search products, brands, and collections | Sets scope before the shopper types; the field is not asking them to guess what is indexed. |
| Label a suggestion | Collection · Waterproof work boots | Lets the shopper recognise the destination instead of decoding an unlabelled list. |
| Keep submission visible | View all results for “waterproof work boot” | Preserves agency when prediction is incomplete or the exact query needs a full page. |
| Explain an empty response | No suggestions yet: search the full catalogue or refine the query | Separates 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.
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.
The dialog keeps a desktop-sized body, so the keyboard covers part of the answer.
The input stays anchored and the response gets the space above the keyboard.
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.
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.
| Layer | Start | End | Inspect |
|---|---|---|---|
| Open | Trigger activation | Named dialog and focused input are ready | Bundle, hydration, focus work, scroll lock, animation |
| Query | Eligible input change | Current request starts | Debounce, composition, main-thread work, cache lookup |
| Response | Request starts | Current response arrives | Network, retrieval, ranking, payload, stale cancellation |
| Render | Current response arrives | Stable suggestions are visible and operable | Parsing, DOM, images, layout, announcement, active option |
| Commit | Selection or submit | Destination or results state is usable | Destination 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_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.
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
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
Walk the state machine
Test closed, opening, idle, querying, results, no suggestions, error, submit, and closing.
Output: A state and transition defect list.
- 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
Exercise autocomplete separately
Test stale responses, arrow keys, Enter, editing, clear, submit, and the destination.
Output: Autocomplete defects separated from dialog-shell defects.
- 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
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
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.