Setting the file. One moment.
Country Selector · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs
Back to the top of the page Mcloud
Country selector allows customers to choose their country/region, which determines currency, pricing, available products, shipping options, payment methods, and localized content.
Display prices in correct currency
Show country-specific product availability
Apply region-specific promotions and discounts
Calculate accurate shipping costs and delivery times
Enable appropriate payment methods
Display localized content and language
Why country/region selection matters:
Prices vary by region (currency, taxes, import fees)
Product availability differs by market
Shipping methods and costs are region-specific
Legal requirements vary (privacy, consumer protection)
Payment methods differ by country
Improves user experience with relevant content
Implement country selector when:
Backend supports multiple countries or regions
Selling to multiple countries or regions
Prices vary by location (currency, taxes)
International shipping with different rates
Region-specific product catalogs
Multi-currency support needed
Legal or regulatory requirements vary by region
Backend doesn’t support multiple countries or regions
All prices in one currency
No regional differences in catalog or pricing
Footer placement (modern and minimal):
Bottom of page in footer
Less prominent but always accessible
Icon (flag or globe) + country code/name
Header placement (most common):
Top-right of navigation bar
Icon (flag or globe) + country code/name
Click opens dropdown or modal selector
Modal/popup on first visit:
Detect location and suggest country
Allow user to confirm or change
Store preference for future visits
Pattern 1: Dropdown (Recommended)
Small, compact selector in header. Shows current country flag/name, click to open dropdown with country list.
Pros: Doesn’t interrupt browsing, always accessible, familiar pattern.
Pattern 2: Modal on First Visit
Full-screen or centered modal on first visit. “Select your country to see accurate prices and shipping.”
Pros: Forces initial selection, ensures accurate pricing from start.
Cons: Can be intrusive, delays browsing.
Tradeoff: Modal ensures selection but adds friction. Dropdown is less intrusive but users may miss it.
Sticky banner at top: “Shipping to United States? Change” with link to selector.
Pros: Non-intrusive reminder, doesn’t block content.
Cons: Takes vertical space, easy to ignore.
Search input at top
Alphabetical country list below
Popular countries at top (US, UK, Canada, etc.)
Flag icons for visual recognition
North America, Europe, Asia, etc.
Collapsible sections
Helpful for large lists (100+ countries)
Show flag, country name, and currency code for clarity.
Client-side storage (recommended):
localStorage or cookies
Persists across sessions
Key: region_id or country_code
Fast access without API call
Available immediately on page load
No server round-trip needed
Recommended: Create context for region/country data.
Provides quick access throughout the app to:
Selected country
Selected region (if applicable)
Currency
Available payment methods
Shipping options
Centralized country/region logic
Easy access from any component
Single source of truth
Simplified cart and product queries
Product price display (convert currency, apply regional pricing)
Cart creation (set region for accurate totals)
Product queries (retrieve accurate pricing)
Checkout flow (shipping methods, payment options)
Content display (language, measurements)
What backend needs to provide:
List of available countries/regions
Mapping of countries to regions (if using regional structure)
Pricing per region or country
Product availability by region
Shipping methods by region
Supported payment methods by region
Fetch country/region list on app load
Pass selected country/region to product queries
Include region in cart creation
Validate country selection on backend
For Medusa users, regions are critical for accurate pricing.
Medusa uses regions (not individual countries) for pricing. A region can contain multiple countries.
Region : Group of countries with shared pricing (e.g., “Europe” region)Country : Individual country within a regionCurrency : Each region has one currency Mapping country to region:
Customer selects country (e.g., “Germany”)
Find which region contains that country (e.g., “Europe” region)
Store region ID for cart and product operations
Use region for all pricing queries
Creating carts: Must pass region ID
Retrieving products: Pass region to get accurate prices
Product availability: Products may be region-specific
Implementation pattern:
Create a context that stores both country and region. When country changes, look up corresponding region and update both.
For detailed Medusa region implementation, see:
Other backends:
Check the ecommerce backend’s documentation for country/region handling patterns.
IP-based geolocation (recommended):
Detect user’s country from IP address. Use as default but allow user to change.
Use geolocation API or service (MaxMind, ipapi.co, CloudFlare)
Server-side detection (more accurate)
Set as default, show confirmation: “Shipping to United States?”
Benefits: Reduces friction, most users keep detected country.
Tradeoff: Not 100% accurate (VPNs, proxies). Always allow manual override.
If detection fails or unavailable:
Check localStorage for previous selection
Use browser language as hint (navigator.language)
Default to primary market (e.g., US for US-based store)
Prompt user to select on first interaction (cart, checkout)
Never block browsing if country unknown.
Allow browsing with default pricing, prompt selection before checkout.
Selector placement:
Mobile hamburger menu or bottom of page. Top-right in mobile header if space allows.
Modal selector:
Full-screen modal on mobile for country selection. Large touch targets (48px), search input at top, easy scrolling.
Sticky reminder:
Small banner: “Shipping to US? Change” with tap to open selector.
Detection prompt:
Bottom sheet: “We detected you’re in Germany. Is this correct?” with Confirm/Change buttons.
Not done: Country selector visible (header, footer, or first-visit modal)Not done: Current country clearly displayed (flag, name, currency)Not done: Dropdown or modal with country listNot done: Search functionality for long country listsNot done: Popular countries at top of listNot done: Flag icons for visual recognitionNot done: Show currency code per countryNot done: localStorage persistence (save selection)Not done: Context provider for region/country dataNot done: Auto-detection based on IP (optional)Not done: Manual override always availableNot done: Apply to product prices (currency, regional pricing)Not done: Apply to cart creation (set region)Not done: Apply to checkout (shipping, payment methods)Not done: Fallback if detection failsNot done: Mobile: Full-screen modal or bottom sheetNot done: Mobile: Large touch targets (48px)Not done: Backend integration (fetch regions, map countries)Not done: For Medusa: Region context with country-to-region mappingNot done: For Medusa: Pass region to cart and product queriesNot done: ARIA label on selector buttonNot done: Keyboard accessible (Tab, Enter, arrows)Not done: Screen reader announces country changes
Not done: Currency conversion display (show original + converted)Not done: Language selector tied to countryNot done: Shipping estimate based on countryNot done: Tax estimation displayNot done: Regional content (images, messaging)Not done: “Not shipping to your country?” alternative reference/components/country-selector.md