Theme Switch Variants

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.

<ThemeModeSegmentedControl />

File Layout

• Directory src

  • Directory components

    • Directory lotus

      • ThemeSwitch.astrolocal override
  • theme.config.tsregisters components.ThemeSwitch

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.

   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.

Segmented Control

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

---
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.

---
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.

---
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.

---
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.

---
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>

export default defineLotusConfig({
  components: {
    HeaderSocialIcons: './src/components/lotus/HeaderSocialIcons.astro',
  },
});

Use Overriding Components for the full override contract and Appearance for the default color mode setting.