--- title: "Language Switcher Guide - PerfLocale" description: "Language switcher options - Gutenberg block, shortcode, widget, PHP template tag, and theme template overrides." canonical: "https://perflocale.com/docs/language-switcher/" source: "https://perflocale.com/docs/language-switcher/" format: "markdown" --- # Language Switcher PerfLocale provides multiple ways to display a language switcher on your site. ## Gutenberg Block Add the **Language Switcher** block from the block inserter (search "Language Switcher" or find it under Widgets). ### Block Settings | Setting | Options | Default | | --- | --- | --- | | Style | Flags + Names, Flags Only, Names Only | Flags + Names | | Layout | Horizontal, Vertical | Horizontal | | Name Format | Native, English, Both - English (Native), Code | Native | | Trigger Label Format (dropdown only) | Match Name Format, Native, English, Both, Code only — controls the dropdown button's visible label independently of the options' format. Use Code only to get a compact "EN" pill in the header while the dropdown lists full names. Hidden when Display Mode is not Dropdown. | Match Name Format | | Show flags | On/Off | On | | Show names | On/Off | On | | Hide current | On/Off | On | | Show untranslated | On/Off | Off | | Dropdown arrow | Single chevron, Double chevrons, None (dropdown style only). Theme override via perflocale/switcher/arrow_html filter. | Single chevron | | Font size | 10–24 px | 14 | | Flag size | 14–40 px | 20 | | Gap | 0–24 px | 8 | The block uses server-side rendering, so you see a live preview in the editor. The block also honors WordPress's standard block supports on the frontend - **Align** (left / center / right / wide / full), **Spacing** (padding / margin), **Color**, **Typography**, and **Additional CSS class** - so the same wrapper classes you see in the editor reach the page. Themes' `is-layout-constrained` layout rules cannot stretch the dropdown trigger to the full content-area width; the wrapper stays sized to the visible button. ## Shortcode: `[perflocale_switcher]` Place this shortcode in any post, page, or widget area. ### Attributes | Attribute | Values | Default | Description | | --- | --- | --- | --- | | style | flags_names, flags_only, names_only | From settings | Display style | | display | inline, simple, dropdown | From settings | Layout mode. dropdown renders a click-to-expand button + listbox panel. | | layout | horizontal, vertical | horizontal | List direction | | name_format | native, english, both, slug | native | How to display language names in the options list | | trigger_format | inherit, native, english, both, slug | inherit | Dropdown trigger button label format. inherit reuses name_format; an explicit value lets the header pill diverge from the options (e.g. slug trigger + native options renders "EN" on the button + "Deutsch / Français" inside the dropdown). Only meaningful when display="dropdown". | | arrow_style | single, double, none | From settings | Dropdown trigger chevron icon. single = one down chevron (classic native-select look); double = stacked up + down chevrons; none = no icon (theme custom icons via the perflocale/switcher/arrow_html filter). Only meaningful when display="dropdown". | | show_flags | 1 / 0 | 1 | Show flag emoji | | show_names | 1 / 0 | 1 | Show language names | | hide_current | 1 / 0 | From settings | Hide the active language | | show_untranslated | 1 / 0 | From settings | Show languages without a translation | | class | CSS class name | (empty) | Custom CSS class | ### Examples ``` [perflocale_switcher] [perflocale_switcher display="dropdown"] [perflocale_switcher style="flags_only" hide_current="1"] [perflocale_switcher style="names_only" name_format="english"] [perflocale_switcher layout="vertical" show_flags="0"] [perflocale_switcher style="flags_names" name_format="both" class="my-switcher"] [perflocale_switcher display="dropdown" arrow_style="double" trigger_format="slug"] ``` ## Widget Go to **Appearance > Widgets** and add the **Language Switcher** widget (in the PerfLocale section, or via the Legacy Widget block). The widget exposes the full set of per-instance options — Display Mode, Style, Layout, Name Format, Trigger Label Format, Dropdown Arrow, Show flags / names, Hide current, Show untranslated, Font / Flag / Gap sizes — matching the Gutenberg block one-for-one. The dropdown-only fields (Trigger Label Format, Dropdown Arrow) default to "Use site default" so existing widget instances keep the global Settings → Language Switcher value until you explicitly override. ## PHP Template Tag In your theme templates: ```php 'flags_names', 'display' => 'dropdown', 'show_flags' => true, 'show_names' => true, 'show_native' => true, 'hide_current' => false, 'name_format' => 'native', 'trigger_format' => 'slug', // "EN" on the trigger button 'arrow_style' => 'double', // up + down chevrons 'class' => 'my-custom-switcher', ] ); ?> ``` ## Per-instance attribute coverage across surfaces Every rendering surface — block, shortcode, template tag, WP widget, page-builder integrations, theme addons, the floating Customizer switcher — supports the same set of per-instance overrides. Unset / empty values fall through to the global **Settings → Language Switcher** defaults, so you can configure the site-wide look once and only override specific instances when needed. | Surface | Trigger Label Format | Dropdown Arrow | | --- | --- | --- | | Gutenberg Block | Inspector → Display | Inspector → Appearance | | Shortcode [perflocale_switcher] | trigger_format="…" | arrow_style="…" | | PHP Template Tag perflocale_language_switcher() | 'trigger_format' => '…' | 'arrow_style' => '…' | | WP Widget (Appearance → Widgets) | Trigger Label Format dropdown | Dropdown Arrow dropdown | | Elementor widget | Trigger Label Format select (dropdown-only) | Dropdown Arrow select (dropdown-only) | | Beaver Builder module | Trigger Label Format select | Dropdown Arrow select | | Bricks element | Trigger Label Format select (dropdown-only) | Dropdown Arrow select (dropdown-only) | | Customizer floating switcher | perflocale_floating_trigger_format control | perflocale_floating_arrow_style control | | Blocksy header + footer language switcher | Trigger Label Format option (dropdown-only) | Dropdown Arrow option (dropdown-only) | | Kadence header switcher | perflocale_kadence_trigger_format Customizer control | perflocale_kadence_arrow_style Customizer control | | Neve header builder component | Trigger Label Format component setting | Dropdown Arrow component setting | The dropdown-only controls (Trigger Label Format + Dropdown Arrow) are hidden in the UI when the surface's Display Mode is set to `inline` / `simple` — there's no trigger button to format in those modes. If you set them anyway (e.g. via shortcode attribute), the block render silently ignores them outside dropdown mode, so it's safe to script. ## Customising the switcher output The switcher HTML is generated in PHP (`src/Frontend/LanguageSwitcher.php` and `LanguageSwitcherBlock.php`) - there are no PHP templates to copy into your theme. Customise it via filters and CSS instead: ``` // 1. Filter the language list before rendering (e.g. hide a language). add_filter( 'perflocale/switcher/languages', function( $languages ) { return array_filter( $languages, fn( $lang ) => $lang->slug !== 'de' ); } ); // 2. Filter the attributes for each link (add data attributes, classes, etc.). add_filter( 'perflocale/switcher/link_attrs', function( $attrs, $lang, $current_slug, $args ) { $attrs['data-track'] = 'lang-switch:' . $lang->slug; return $attrs; }, 10, 4 ); // 3. Inject HTML at the start / end of the dropdown panel. // Useful for region groupings, search inputs, branding chrome, etc. // Returned HTML is sanitised through kses_switcher() — extend the // allowlist with perflocale/switcher/kses_allowed_html if needed. add_filter( 'perflocale/switcher/panel_before', function( $html, $languages, $current_slug, $attrs ) { return ''; }, 10, 4 ); // 4. Swap the dropdown chevron for a custom icon. add_filter( 'perflocale/switcher/arrow_html', function( $html, $style ) { return ''; }, 10, 2 ); // 5. Filter the inner HTML of every option (flag + label). // Same callback fires from dropdown, inline, and simple paths. add_filter( 'perflocale/switcher/option_content', function( $inner, $lang ) { // Wrap in for safe mixed-direction rendering of e.g. // "العربية" inside an LTR option list. return '' . $inner . ''; }, 10, 2 ); // 6. Filter the entire rendered HTML as a last-resort override. add_filter( 'perflocale/switcher/output', function( $html, $args ) { // Wrap the switcher in your own container, swap markup, etc. return '
' . $html . '
'; }, 10, 2 ); ``` Built-in CSS class hooks (target these in your theme stylesheet to restyle without touching markup): - `.perflocale-switcher-block` - root nav element on the block/shortcode switcher - `.perflocale-switcher-block--dropdown` / `.perflocale-switcher-block--horizontal` / `.perflocale-switcher-block--vertical` / `.perflocale-switcher-block--simple` - mode modifier (set from the block’s _Display_ attribute) - `.perflocale-switcher-block__item`, `.perflocale-switcher-block__item--current`, `.perflocale-switcher-block__label`, `.perflocale-switcher-block__flag` - per-language item internals (used by horizontal / vertical / simple modes) - `.perflocale-dd__anchor` - inline-block wrapper inside the dropdown `