Search

• Overview
• Search Placement
• Autocomplete and Product Suggestions
• Search Results Page
• Empty States
• Recent and Popular Searches
• Mobile Search

Overview

Search is critical for ecommerce - users with search intent convert at higher rates. Provide fast, relevant product discovery with autocomplete.

Assumed knowledge: AI agents know how to build search inputs with icons and clear buttons. This guide focuses on ecommerce search patterns.

Key Requirements

• Prominent search input (always accessible)
• Instant autocomplete after 2-3 characters
• Product suggestions with images
• Fast, relevant search results
• Filters to refine results
• Empty state guidance
• Mobile full-screen search modal

Search Placement

Desktop: Navbar center (between logo and cart) or right side. Always visible, 300-500px width. Part of sticky navbar. Never hide in hamburger menu.

Mobile: Magnifying glass icon in top-right (44x44px minimum). Opens full-screen modal - eliminates distractions, maximizes suggestion space, better typing experience.

Autocomplete and Product Suggestions

Show suggestions after 2-3 characters (not 1). Debounce 300ms to prevent excessive API calls.

Display 5-10 product suggestions:

• Small image (40-60px), title, price
• Clickable to product page
• Optional: Category/brand suggestions, popular terms
• Divide sections with headers
• “View all results for [query]” footer link

Backend integration: Fetch from search API. Check with ecommerce platform’s documentation for API reference.

Search Results Page

Header: “Search Results for ‘[query]’” + result count (“24 products found”). Search bar visible and pre-filled for refining.

Grid layout: Same as product listings (see product-listing.md). 1-4 columns based on device.

Sorting: Relevance (default, unique to search), Price Low/High, Newest.

Filters: Sidebar (desktop) or drawer (mobile). Category, Price, Brand, Availability with result counts.

Empty States

No results: “No results for ‘[query]’” with helpful suggestions (check spelling, try broader keywords, browse categories). “Browse All Products” button + links to popular categories.

Loading state: Product card skeletons (6-8 cards), minimum 300ms display to avoid flashing.

Recent and Popular Searches

Recent searches (user-specific, localStorage): Show 3-5 recent searches when input focused (before typing). Helps re-search without retyping.

Popular searches (site-wide, from backend): Show 5-10 trending terms when focused. Pill/tag styling.

Display both on: Empty input focus (desktop dropdown), mobile modal open.

Mobile Search

Full-screen modal pattern:

• Header: Back button (44x44px) + search input (48px height, auto-focus, type="search")
• Content: Recent/popular searches (empty), autocomplete (typing), scrollable
• Close: Back button, device back gesture, Escape key

Ecommerce Search Checklist

Essential features:

• Not done: Prominent search input in navbar (desktop)
• Not done: Search icon clearly visible (mobile)
• Not done: Full-screen modal on mobile tap
• Not done: Autocomplete after 2-3 characters
• Not done: Debounced API calls (300ms)
• Not done: Product suggestions with images, prices
• Not done: “View all results” link in dropdown
• Not done: Search results page shows query
• Not done: Result count displayed
• Not done: Sort by Relevance (default for search)
• Not done: Filters for refining results (category, price, brand)
• Not done: Empty state with helpful guidance
• Not done: Loading state indicator (skeleton)
• Not done: Recent searches (localStorage)
• Not done: Popular searches (from backend)
• Not done: Mobile: Auto-focus, large input (48px)
• Not done: Keyboard navigation (arrow keys, Enter, Escape)
• Not done: ARIA labels (role="search", aria-label)
• Not done: Accessible to screen readers