# Theme Switch Variants

Replace the default theme switch with another built-in color mode control.

import { FileTree, Steps } from '@prosefly/astro-components';
import ThemeSwitchVariantDemo from '@/components/ThemeSwitchVariantDemo.astro';

Use this recipe when the default segmented theme switch is not the right shape
for the header or mobile menu. Lotus exports several ready-made theme mode
controls, and each one can be used as the `ThemeSwitch` override slot.

All built-in controls use the same `lotus-theme` local storage key and update
the same `data-theme` attribute. `appearance.defaultMode` only controls the
initial mode before a visitor chooses a preference.

<ThemeSwitchVariantDemo />

## File Layout

<FileTree>

- src
  - components
    - lotus
      - ThemeSwitch.astro local override
  - theme.config.ts registers `components.ThemeSwitch`

</FileTree>

<Steps>

1. **Choose one built-in theme mode control.**

   Use `ThemeModeSegmentedControl`, `ThemeModeButton`, `ThemeModeSelect`, or
   `ThemeModeSwitch`.

2. **Create a local `ThemeSwitch` override.**

   Import the chosen public component from
   `@prosefly/astro-theme-lotus/components` and render it directly.

3. **Register the override.**

   ```ts title="src/theme.config.ts"
   export default defineLotusConfig({
     components: {
       ThemeSwitch: './src/components/lotus/ThemeSwitch.astro',
     },
   });
   ```

4. **Keep the override self-contained.**

   The built-in components already include the client controller they need.

</Steps>

## Segmented Control

Use the segmented control when all three modes should be visible at once. This
is the Lotus default.

```astro title="src/components/lotus/ThemeSwitch.astro"
---
import { ThemeModeSegmentedControl } from '@prosefly/astro-theme-lotus/components';
---

<ThemeModeSegmentedControl />
```

## Cycle Button

Use this when header space is tight. The button cycles through `system`,
`light`, and `dark`.

```astro title="src/components/lotus/ThemeSwitch.astro"
---
import { ThemeModeButton } from '@prosefly/astro-theme-lotus/components';
---

<ThemeModeButton />
```

## Select Menu

Use this when labels are clearer than icons. The component renders a native
select on small screens and a compact dropdown on larger screens.

```astro title="src/components/lotus/ThemeSwitch.astro"
---
import { ThemeModeSelect } from '@prosefly/astro-theme-lotus/components';
---

<ThemeModeSelect />
```

## Light/Dark Switch

Use this when the project does not want to expose a visible system option. The
stored mode can still start from `appearance.defaultMode`, but this control only
lets visitors choose light or dark.

```astro title="src/components/lotus/ThemeSwitch.astro"
---
import { ThemeModeSwitch } from '@prosefly/astro-theme-lotus/components';
---

<ThemeModeSwitch />
```

## Custom Placement

`ThemeSwitch` renders in both the desktop header and mobile menu. If those
contexts need different controls, override `HeaderSocialIcons` instead and
branch on the `mobile` prop.

```astro title="src/components/lotus/HeaderSocialIcons.astro"
---
import {
  SocialIcons,
  ThemeModeButton,
  ThemeModeSelect,
} from '@prosefly/astro-theme-lotus/components';

interface Props {
  mobile?: boolean;
}

const { mobile = false } = Astro.props;
---

<div class:list={['flex items-center', mobile ? 'gap-2' : 'gap-3']}>
  <SocialIcons mobile={mobile} />
  {mobile ? <ThemeModeSelect /> : <ThemeModeButton />}
</div>
```

```ts title="src/theme.config.ts"
export default defineLotusConfig({
  components: {
    HeaderSocialIcons: './src/components/lotus/HeaderSocialIcons.astro',
  },
});
```

Use [Overriding Components](/docs/customization/overriding-components/) for the
full override contract and [Appearance](/docs/configuration/appearance/) for
the default color mode setting.