Download the PHP package bezhansalleh/filament-language-switch without Composer

Language Switch

Zero-config language switching for Filament Panels. Drop it in, provide your locales, and you're done. The plugin auto-detects your panel layout and renders in the right place with the right design — topbar icon button, sidebar nav item, user menu item — without any manual wiring.

Table of Contents

• Installation
• Quick Start
• Display Modes
• Trigger
• Flags
• Labels
• Appearance
• Placement
• Outside Panels
• Inline Embedding
• Panel Exclusion
• User Preferred Locale
• Customization
• Event
• Control Panel
• Full Example
• Version Support

Installation

[!IMPORTANT] The plugin follows Filament's theming rules. So, to use the plugin create a custom theme if you haven't already, and add the following line to your theme.css file:

Now build your theme using:

Build your theme:

Quick Start

Add this to any service provider's boot() method:

That's it. The switch appears in your topbar automatically. When the panel has no topbar, it moves to the sidebar.

Display Modes

Dropdown (default)

The trigger opens a dropdown with your locales. The list is scrollable by default (max-height: 18rem), so it stays usable with many locales:

Modal

Opens a modal dialog instead. Better for many languages:

Modal with Grid

Arrange locales in columns:

Slide-over

Modal Heading & Icon

Trigger

The trigger is configured through a single unified trigger() method that takes a style and/or an icon. Both are optional — pass whichever you want to override.

Trigger Style

Use the TriggerStyle enum to control what the trigger shows. The default adapts to the render context automatically (e.g. flag if you've set flags, otherwise icon in topbar; icon+label in sidebar/user menu), so you only need to call this when you want to override it:

Trigger Icon

The trigger uses the language icon by default. Pass any icon from your installed Blade Icons packages, or a Heroicon enum case:

You can also override the icon globally via Filament's icon alias system:

Flags

Associate each locale with a flag image:

Item Style

Control what each locale item shows in the dropdown or modal. The default auto-detects: FlagWithLabel when flags are configured, AvatarWithLabel otherwise.

Compact styles (FlagOnly, AvatarOnly) use the same tight cell layout with tooltips. In modal mode, FlagOnly renders as a showcase grid with radio-card selection; AvatarOnly falls back to label-only cards since the abbreviation is too small for a showcase.

Labels

Custom Labels

Override the auto-generated locale names:

Native Labels

Show each locale name in its own language (e.g., "Français" instead of "French"):

Display Locale

Change the language used for auto-generated labels:

Appearance

Circular

Make flags and avatars fully rounded:

Flag & Avatar Sizing (Modal)

Control sizes in modal radio cards:

Placement

Render Hook

Place the switch at any Filament render hook:

The trigger automatically adapts its design to match the surrounding UI:

Any other hook works too. If you pass a hook the plugin doesn't explicitly classify, it still registers and renders a default icon button — but the visual fit is on you. Use the stable CSS hooks (fi-ls, fi-ls-trigger, etc.) from your own stylesheet, or publish the views for structural changes.

Smart Defaults

When you don't set a render hook, the plugin picks the best one based on your panel:

To render inside the user menu as a menu item, set the render hook explicitly:

Dropdown Placement

Control which direction the dropdown opens:

Max Height

The dropdown is scrollable by default (18rem). Override it for a different limit, or pass 'max-content' to disable scrolling:

Outside Panels

Filament's unauthenticated pages (login, register, password reset, email verification) render in a simple layout — no sidebar, no topbar, just the centered form card. You can show the language switcher on these pages so visitors can translate the UI before they sign in.

visible() takes two independent toggles — insidePanels (default true) and outsidePanels (default false) — so you can enable either context on its own, both, or neither. For example, to render only on the simple-layout pages and hide the switcher once the user is inside the panel:

By default the switcher renders as a content-sized pill anchored to the chosen Placement. All six placements are RTL-aware — start/end auto-flip for right-to-left locales:

Placement mode

outsidePanelPlacement() accepts an optional second argument that controls how the switcher is attached to the page. Three modes, each with predictable CSS semantics — the names are chosen so they match what you'd read in the published view:

Naming note: we use Pinned instead of Fixed on purpose. In CSS, position: fixed means "always visible, stays on screen during scroll" — which in the dev brain is usually called "sticky". To avoid that collision every time someone opens the blade file, the mode is named after the intent (Pinned = pinned to viewport), while Static and Relative use the literal CSS names because those map 1:1 to their CSS behavior.

Which routes it shows on

By default the switcher appears on Filament's standard auth routes. Override the list if your panel uses different route names:

The default list is ['auth.login', 'auth.profile', 'auth.register']. The profile route is automatically excluded from the match unless the current panel uses a simple profile page (->profile(isSimple: true)), since a full-layout profile page already has a topbar/sidebar where the switcher lives.

Render hook anchor (auto-derived)

The anchor hook is derived from both the placement and the mode — you don't pick it manually:

You can still override explicitly — pass any hook name to outsidePanelsRenderHook():

Auto-docking into the user menu

When all of these are true, TopEnd automatically docks into the user menu via USER_MENU_BEFORE instead of anchoring as a pinned overlay:

• PlacementMode::Pinned
• The current route is in the outside-panel list (e.g. a simple profile page)
• The user is authenticated
• The panel has a user menu

This avoids the collision between the pinned pill and Filament's own .fi-simple-layout-header (also anchored at top-0 end-0). Static and Relative modes don't trigger auto-docking because they're in flow and can't collide with the header.

To force a pinned overlay regardless, pin a different hook explicitly:

Inline embedding in custom pages

The render-hook system handles the common cases automatically — topbar, sidebar, user menu, simple layout. If you need to drop the switcher into a custom page section or arbitrary location in your own views, use the Blade component:

It mounts the same <livewire:language-switch-component> directly at the tag's position — no render hook required. The trigger uses whatever styling your current configuration resolves to (for example, if your effective render hook is in the topbar, you'll get a topbar-style icon button inline in your view). If you need a different visual in your custom location, override with ->renderHook(...) in a dedicated configureUsing callback or publish the views for full control.

Passing an explicit key is recommended when embedding in a parent component that re-renders, or when placing multiple instances on the same page:

If omitted, a unique key is auto-generated via uniqid() on every render, which is fine for static pages but can cause the component to re-mount unnecessarily on dynamic parent updates.

Panel Exclusion

Hide the switch from specific panels:

User Preferred Locale

Resolve the user's preferred locale from their profile or any source:

The locale resolution order is:

1. Session
2. Query parameter (?locale=)
3. User preferred locale (this setting)
4. Browser Accept-Language header
5. Cookie
6. app.locale config

Customization

For deep customization, publish the plugin's views and edit them in your app:

Published views live in resources/views/vendor/language-switch/ and override the package versions automatically. For small tweaks, prefer targeting the plugin's stable CSS hooks (fi-ls, fi-ls-trigger, fi-ls-item, etc.) from your own stylesheet rather than publishing views.

Event

A LocaleChanged event fires whenever the locale switches:

Control Panel

A floating developer configurator that lets you hot-swap every configuration option live in the browser — handy for previewing trigger styles, testing render-hook placements, and checking the outside-panel modes without editing your service provider.

Enabling it

Opt in explicitly via controlPanel():

Disabled by default. When you call controlPanel() (or controlPanel(true)) and the app is running with APP_ENV=local + APP_DEBUG=true, a small language-icon button appears at the bottom-end of every panel page. The local + debug requirement is a safety guardrail — even if you leave controlPanel(true) committed, it won't render in production.

To disable it explicitly (e.g. in a shared configuration):

Live vs manual mode

controlPanel() takes two arguments: controlPanel(bool $enabled = true, bool $live = true). By default every change (toggle, select) is applied immediately via a Livewire round-trip. If you'd rather stage multiple changes and commit them together, pass live: false:

In manual mode, changes are accumulated in the session and the panel footer shows an Apply button (only enabled when you have pending changes). Click it to commit everything in one reload. Reset still works the same way — it wipes every accumulated override and restores your configured defaults.

Sections

The panel is organized as an accordion — click a section to expand it; opening one collapses the others, so it stays compact on both mobile and desktop:

• Trigger — topbar on/off, trigger style, trigger icon, render hook
• Display — dropdown / modal mode, modal width, columns, slide-over
• Appearance — circular, native labels, use flags, item style
• Outside Panels — enable toggle, placement, placement mode (Pinned / Static / Relative), and an explicit render hook override (defaults to auto, with user-menu docking targets as alternatives)

Full Example

Version Support

Only the latest major plugin line receives active development. Older lines stay installable for legacy projects but get no new features; they only receive security fixes while their Filament target is still supported upstream.

See CHANGELOG for migration notes between majors.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Bezhan Salleh
• All Contributors

License

The MIT License (MIT). Please see License File for more information.