> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devdeia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the package, publish assets, and register the plugin.

<Steps>
  <Step title="Install via Composer">
    ```bash theme={null}
    composer require andreia/filament-ui-switcher
    ```

    The package auto-registers via Laravel's package discovery.
  </Step>

  <Step title="Publish assets">
    This package uses Filament's asset management system:

    ```bash theme={null}
    php artisan filament:assets
    ```

    This publishes the CSS to `public/css/andreia/filament-ui-switcher/`, where Filament loads and browser-caches it automatically.

    <Note>
      Run `php artisan filament:assets` again after every package update to pick up the latest assets.
    </Note>
  </Step>

  <Step title="Publish the config (optional)">
    ```bash theme={null}
    # Publish config
    php artisan vendor:publish --tag=filament-ui-switcher-config

    # Publish translations
    php artisan vendor:publish --tag=filament-ui-switcher-translations
    ```

    Creates `config/ui-switcher.php` — see [Configuration](/filament/filament-ui-switcher/configuration) for every option.
  </Step>

  <Step title="Publish the view (optional)">
    ```bash theme={null}
    php artisan vendor:publish --tag=filament-ui-switcher-views
    ```
  </Step>

  <Step title="Register the plugin">
    Add it to your Filament panel provider (e.g. `app/Providers/Filament/AdminPanelProvider.php`):

    ```php theme={null}
    use Andreia\FilamentUiSwitcher\FilamentUiSwitcherPlugin;

    public function panel(Panel $panel): Panel
    {
        return $panel
            ->id('admin')
            ->path('admin')
            // ... other config
            ->plugin(FilamentUiSwitcherPlugin::make());
    }
    ```

    A ⚙️ settings icon now appears in your topbar.
  </Step>

  <Step title="Register the vendor directory in your theme (recommended)">
    Filament recommends a [custom theme](https://filamentphp.com/docs/4.x/styling/overview#creating-a-custom-theme) so its Tailwind classes get picked up. Add this package's vendor directory to your theme's `theme.css` (usually `resources/css/filament/admin/theme.css`):

    ```css theme={null}
    @source '../../../../vendor/andreia/filament-ui-switcher';
    ```

    Then rebuild:

    ```bash theme={null}
    npm run build
    ```
  </Step>
</Steps>

## Customize icon position

By default, the settings icon appears before the user menu (`USER_MENU_BEFORE`) in the topbar. Point it at any Filament render hook instead:

```php theme={null}
use Andreia\FilamentUiSwitcher\FilamentUiSwitcherPlugin;
use Filament\View\PanelsRenderHook;

FilamentUiSwitcherPlugin::make()
    ->iconRenderHook(PanelsRenderHook::TOPBAR_END)
```

Available hooks for the icon: `USER_MENU_BEFORE` (default), `USER_MENU_AFTER`, `TOPBAR_START`, `TOPBAR_END`, `GLOBAL_SEARCH_BEFORE`, `GLOBAL_SEARCH_AFTER`, or any custom render hook you've defined.

## Enable the mode switcher (optional)

The light/dark/system mode switcher is hidden by default. To include Filament's native mode switcher inside the settings modal:

```php theme={null}
FilamentUiSwitcherPlugin::make()
    ->withModeSwitcher()
```