Customizing the Magento 2 Store Switcher: Hyvä, Alpine.js and URL Logic

1. Why the store switcher is more than a dropdown

For the customer, the Magento 2 store switcher is a simple element in the header, usually displayed as a dropdown with country or language flags. Technically, however, it hides an interplay of store resolution, URL structure, redirect handling and optionally cookie persistence that, if implemented poorly, leads to exactly the frustrating moments an international shop wants to avoid: the customer switches language and suddenly lands on the homepage instead of the product page they were just viewing.

This complexity is often underestimated because the standard store switcher genuinely works unremarkably in a simple single-language installation. As soon as multiple store views with different URL strategies are combined, however, for example store code in the URL versus separate domains, the Magento 2 store switcher needs to be deliberately customized to work consistently. The following sections show how the native mechanism works and how it can be robustly extended in Hyvä with Alpine.js.

2. The native store switcher block and its data model

The native store switcher is based on Magento\Store\Block\Switcher, which delivers all visible stores of the current website or store group via getStoreSwitcherOptions(). For each option a URL is calculated pointing to the same page in the target store, provided a store URL rewrite exists for it. If no matching rewrite exists, for example because a product is not visible in that store, the calculated URL points to the target store's homepage instead.

A central building block is the query parameter ___store, which Magento appends to the calculated URL. This parameter is evaluated by Magento\Store\App\Response\Redirect and triggers a server-side redirect with the store cookie set before the actual target page is delivered. Anyone customizing the Magento 2 store switcher should not bypass this mechanism but deliberately extend it, since it already takes care of the correct store initialization for the entire subsequent request.

<?php

declare(strict_types=1);

namespace Mironsoft\StoreSwitcher\ViewModel;

use Magento\Framework\View\Element\Block\ArgumentInterface;
use Magento\Store\Model\StoreManagerInterface;
use Magento\Store\Api\Data\StoreInterface;

/**
 * ViewModel providing switcher options filtered by an allowed store list.
 */
final class SwitcherOptions implements ArgumentInterface
{
    /**
     * @param StoreManagerInterface $storeManager Resolves all active stores
     */
    public function __construct(
        private readonly StoreManagerInterface $storeManager
    ) {
    }

    /**
     * Return visible stores excluding staging/internal store views.
     *
     * @return StoreInterface[] Store views eligible for the switcher
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function getVisibleStores(): array
    {
        $stores = $this->storeManager->getStores();
        return array_filter(
            $stores,
            static fn (StoreInterface $store): bool => !str_starts_with(
                (string) $store->getCode(),
                'internal_'
            )
        );
    }
}

3. Implementing the store switcher in Hyvä with Alpine.js

In Hyvä, a lightweight phtml template with Alpine.js replaces Luma's heavyweight Knockout.js implementation. The Magento 2 store switcher can be implemented as a simple x-data component that holds the dropdown state and navigates directly to the calculated store URL on click. It is important that the URLs already computed by the block, including the ___store parameter, are carried over unchanged, so the native redirect mechanism continues to apply.

For the visual styling, a Tailwind-based dropdown structure without an additional JavaScript bundle is sufficient in Hyvä, since Alpine.js is already part of the theme. The advantage over the Luma variant lies not only in load time but also in clarity: the entire logic of the store switcher is visible in a single phtml file with a few lines of Alpine.js markup, instead of being spread across several Knockout components.

<?php
/** @var \Magento\Store\Block\Switcher $block */
/** @var \Magento\Framework\Escaper $escaper */
$switcherViewModel = $block->getData('viewModel');
?>
<div x-data="{ open: false }" class="relative" @click.outside="open = false">
    <button
        @click="open = !open"
        class="flex items-center gap-2 text-sm font-medium text-gray-700 hover:text-gray-900"
        aria-haspopup="listbox"
        :aria-expanded="open.toString()"
    >
        <?= $escaper->escapeHtml($block->getCurrentStoreName()) ?>
        <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"/>
        </svg>
    </button>
    <ul
        x-show="open"
        x-transition
        x-cloak
        class="absolute right-0 mt-2 w-48 bg-white border border-gray-200 rounded-lg shadow-lg z-20"
        role="listbox"
    >
        <?php foreach ($block->getStoreSwitcherOptions() as $store): ?>
        <li>
            <a href="<?= $escaper->escapeUrl($store->getUrl()) ?>"
               class="block px-4 py-2 text-sm text-gray-700 hover:bg-gray-50"
               data-store-code="<?= $escaper->escapeHtmlAttr($store->getCode()) ?>">
                <?= $escaper->escapeHtml($store->getName()) ?>
            </a>
        </li>
        <?php endforeach; ?>
    </ul>
</div>

4. Redirect logic: store code in URL versus store code cookie

Magento supports two fundamental URL strategies for store views, controlled via web/url/use_store. If this option is enabled, the store code appears as part of the path, for example /de/product.html, which technically makes the store switcher simpler, since the URL itself already uniquely maps to a store. If the option is disabled, the recommended default for production shops, URLs are identical per store view, and Magento distinguishes solely via domain, cookie, or the ___store parameter on the initial request.

The disabled variant with separate domains per store is significantly more SEO-friendly, since it avoids duplicate content across identical paths, but it requires a more careful store switcher implementation: the switcher must actively link to the correct domain including the store parameter when switching, instead of relying on automatic path detection. A common mistake is rewriting the store switcher client-side via JavaScript without going through the server-side redirect mechanism, which causes the store cookie to not be set correctly and the next page load to land back in the old store.

#!/usr/bin/env bash
set -euo pipefail

# Verify the native ___store redirect actually sets the store cookie
curl -sI "https://shop.example.com/product.html?___store=at" \
  | grep -iE 'location|set-cookie'

# Expected: a 302/301 redirect to the clean URL plus
# Set-Cookie: store=at; ...
# If Set-Cookie is missing, the redirect mechanism was bypassed somewhere
# (e.g. a client-side rewrite instead of following the native link)

5. Preserving page context when switching

One of the biggest expectations for a well-built store switcher is that the customer lands on the same content page after switching language, for example the same product in the new language, instead of the homepage. Magento fundamentally solves this via URL rewrites: if a rewrite exists for the current entity, for example a product or a category, in the target store, getStoreSwitcherOptions() automatically calculates the matching URL for that store.

It becomes problematic when a product is not assigned or not visible in the target store. In this case Magento falls back to the store homepage, which feels like an error to the customer, even though it is technically correct behavior. A sensible extension of the store switcher is therefore to show the customer a brief message in this case, such as "This product is not available in the selected store, find similar items here", instead of leaving them on the homepage without explanation.

6. Cookie persistence and returning visitors

For returning visitors, it makes sense to persist the store decision made once beyond the current visit, so the store switcher does not need to be operated again on every new visit. Magento automatically sets the store cookie for this when switching via the ___store parameter, whose lifetime is configured via web/cookie/cookie_lifetime. On a repeat visit without an explicit store parameter in the URL, Magento falls back to this cookie, provided no other mechanism, such as domain-based routing, takes precedence.

For GDPR-compliant implementations it should be noted that this cookie is functionally necessary and generally may be set without explicit consent, as long as it serves purely the technical store assignment and pursues no tracking purposes. If the store switcher is extended with additional preferences, for example a remembered preferred currency independent of the store, this extension should be listed separately in the cookie consent banner to stay on the legally safe side.

7. Controlling store visibility by customer group or GeoIP

Not every store view should be visible to every visitor in the store switcher. A B2B store view, for example, may need to appear only for logged-in business customers, while a store view for a country not yet officially launched should remain visible only for internal testing purposes. The native block does not ship with this filtering logic, which is why a plugin on getStoreSwitcherOptions() is needed that filters the list based on customer group, GeoIP detection, or a custom release flag per store view.

GeoIP-based filtering must be implemented with particular care, since it should never fully hide a store selection that a customer deliberately reached via a direct link. The store switcher may restrict the list of visible options, but direct access via an explicit store URL should continue to work regardless of GeoIP detection, otherwise support requests arise from customers who arrive via a shared link and suddenly see nothing.

<?php

declare(strict_types=1);

namespace Mironsoft\StoreSwitcher\Plugin;

use Magento\Store\Block\Switcher;
use Magento\Customer\Model\Session as CustomerSession;

/**
 * Filters the visible store switcher options by customer group,
 * hiding B2B-only store views from guests and retail customers.
 */
final class FilterSwitcherByCustomerGroup
{
    private const int B2B_STORE_ID = 5;
    private const int B2B_CUSTOMER_GROUP_ID = 3;

    /**
     * @param CustomerSession $customerSession Current customer session
     */
    public function __construct(
        private readonly CustomerSession $customerSession
    ) {
    }

    /**
     * @param Switcher $subject Native store switcher block
     * @param array $result Native list of switcher options
     * @return array Filtered list, excluding B2B store views for non-B2B customers
     */
    public function afterGetStoreSwitcherOptions(Switcher $subject, array $result): array
    {
        if ($this->customerSession->getCustomerGroupId() === self::B2B_CUSTOMER_GROUP_ID) {
            return $result;
        }

        return array_filter(
            $result,
            static fn ($store): bool => (int) $store->getId() !== self::B2B_STORE_ID
        );
    }
}

8. SEO impact: thinking hreflang and store switcher together

The store switcher and the hreflang links in a page's head section should always use the same data source. A common, hard-to-find bug occurs when both elements are implemented independently and thereby compute different store URLs, for example because the store switcher uses different client-side logic than the server-rendered hreflang tag. Search engines interpret such inconsistencies as a signal of unreliable international audience targeting.

A clean architecture pulls the store URL calculation into a central ViewModel class consumed both by the hreflang block in the head and by the store switcher in the header. This unification ensures both elements always reference the same target URLs, regardless of where in the layout they are rendered, and significantly reduces the risk of contradictory international signals.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Magento\Store\Block\Switcher">
        <plugin name="mironsoft_filterSwitcherByCustomerGroup"
                type="Mironsoft\StoreSwitcher\Plugin\FilterSwitcherByCustomerGroup"
                sortOrder="10" />
    </type>
</config>

9. Implementation approaches compared

The following overview compares the three most common implementation approaches for the Magento 2 store switcher.

For international shops with more than two or three store views, the third approach is almost always worth it, since the one-time investment in a central ViewModel rules out later inconsistencies between the store switcher and SEO tags from the start.

10. Summary

A robust Magento 2 store switcher uses the native ___store redirect mechanism instead of bypassing it via client-side JavaScript, and thereby preserves correct cookie state for the entire session. In Hyvä, the switcher can be elegantly implemented with Alpine.js without altering the store URLs already computed by the native block. Page context is preserved as long as a matching URL rewrite exists in the target store, otherwise the customer should see an explanatory message instead of a silent redirect to the homepage.

Store visibility by customer group or GeoIP requires a custom plugin, but should never block direct access via an explicit store URL. The biggest quality improvement comes from having the store switcher and hreflang tags use the same central URL calculation instead of being maintained independently.

11. FAQ: Magento 2 Store Switcher