Skip to main content
A navbar locale selector has two parts:
  • Liquid renders the countries, languages, and current selections.
  • Theme JavaScript passes the selected ISO codes to the storefront SDK and then reloads the storefront path.
Use window.FairShareSDK.updateLocaleSettings() for the update. Do not set Fluid locale cookies yourself.

Render the controls

Navbar templates receive countries and language_options directly. Each entry has an iso value and a selected boolean.
Use the ISO values without translating or replacing them. Country values look like us or gb in Liquid. Language values look like en or fr. Send country codes in uppercase and language codes in lowercase. If you render separate desktop and mobile selectors, give their form controls unique id values. Keep the same name values so one JavaScript handler can support both forms.

Apply the selection

Put this code in a theme JavaScript asset loaded after the navbar markup or with defer:
Wait for updateLocaleSettings() before you navigate. The method first stores normalized locale, language, and country values in session cookies. If a cart exists, it then updates the cart language followed by the cart country and saves the returned cart state. If no cart exists, it stores the locale without making a cart request. The method does not reload the page. If a cart update fails, its Promise rejects after the locale cookies have already changed. Handle that error before you decide whether to navigate. Remove only the lang query override before navigating so it does not win over the saved language. Keep the remaining query parameters so theme preview context survives the reload. The reload lets Fluid render translated content and country-specific pricing for the new selection. Your layout must render {{ content_for_header }} so Fluid can load the storefront SDK. See install FairShare if you manage the SDK script yourself.

Customize the included Base theme

The included Base theme uses the same update flow with separate desktop and mobile interfaces. Its CSS classes and IDs are theme hooks, not required platform names. The desktop controls are native <select> elements enhanced with Tom Select. The mobile controls copy the chosen item’s data-value into the current .country-selector or .language-selector element. Both interfaces pass the selected values to updateLocaleSettings() when the shopper applies the change. Use window.FairShareSDK when you customize this flow.

Test the selector

Test the selector with and without an existing cart. Confirm that the next render shows the selected language, country, prices, and cart state. Test it in theme preview and confirm that the preview remains active after the reload. Also test both keyboard and touch interaction if your theme presents different desktop and mobile controls. For every localization field available to Liquid, see theme variables. For the SDK method and related settings helpers, see FairShare shop settings.