Icon Theme Toggle

Animate between sun and moon icons while changing the UI theme.

Preview

This component uses Vue and Reka. Install the source below in your Vue or Nuxt app to try it with your theme provider.

Examples

Theme transition

A slide transition declared on this control. Duration is 500 milliseconds. Other controls keep their own settings.

This component uses Vue and Reka. Install the source below in your Vue or Nuxt app to try it with your theme provider.

Shadow borders

Use a prominent ambient shadow and inset edge in place of a solid border.

This component uses Vue and Reka. Install the source below in your Vue or Nuxt app to try it with your theme provider.

Slide icons

Sun and moon exchange places with a short sideways movement.

This component uses Vue and Reka. Install the source below in your Vue or Nuxt app to try it with your theme provider.

Blur icons

A brief blur and crossfade joins the two states.

This component uses Vue and Reka. Install the source below in your Vue or Nuxt app to try it with your theme provider.

When to use

Use a compact light/dark action in a header or toolbar.
Use a short icon animation to make the changed state clear.

When not to use

People need to choose the system preference. Use Theme Switcher or Theme Selector.
The control changes a palette. Use Color Theme Selector.

Installation

Set up uitheme-web in an existing Tailwind app. Then install the component. The CLI copies Icon Theme Toggle and its Theme Toggle dependency. Both reuse the shared cn utility.

Tailwind version

Source language

npx uitheme-cli add icon-theme-toggle --base reka --tailwind 4 --language ts

Usage

Use the control inside your theme provider. Import it from your app’s component directory.

example.vue

<script setup lang="ts">
import { UIThemeProvider } from 'uitheme-web/vue';
import IconThemeToggle from '@/components/ui/icon-theme-toggle.vue';
</script>

<template>
  <UIThemeProvider>
    <IconThemeToggle />
  </UIThemeProvider>
</template>

API reference

These props belong to the installed control. Its page transition settings override the provider for this action only.

Prop	Type	Behavior
`label`	`string`	Override the readable accessible label.
`borderStyle`	`'solid' \| 'shadow'`	Use the default solid border or prominent shadow borders. Both use the same space and theme tokens.
`class`	`string`	Extend the root styles. Your classes replace default classes through the local merge helper.
`classes`	`object`	Style the root and trigger parts.
`disabled`	`boolean`	Disable interaction. Preference controls also wait for the provider to mount.
`animationType`	`ThemeAnimationType`	Override the UI theme transition for this control. Defaults to the provider setting.
`duration`	`number`	UI theme transition duration in milliseconds. Defaults to the provider setting.
`slideDirection`	`SlideDirection`	Valid only with animationType set to ThemeAnimationType.SLIDE. Other animation types do not accept this prop.
`effect`	`'rotate' \| 'slide' \| 'blur'`	Icon motion only. Defaults to rotate and is separate from the page transition.

Keyboard

Key	Action
Enter / Space	Toggle the resolved light/dark theme. Keyboard activation changes state without icon movement.

Accessibility

Keep the accessible label when changing the visible content. Icons are decorative.
The control stays disabled until the theme provider mounts.
Reduced motion removes travel and rotation. Icon state keeps a short opacity change. The selection surface changes position without travel.
Keyboard activation changes the theme without the pointer animation.

The sun represents resolved light mode. The moon represents resolved dark mode. Activation replaces a system preference with the opposite resolved theme. The clicked button sets the page transition origin.

AI Agent notes

Use uitheme-web/react for React or uitheme-web/vue for Vue. Keep the theme provider around the control.
Keep page transitions in the control’s animationType and duration props. Do not add a standalone transition-settings control.
Keep input labels, focus styles, selected state, disabled state, and reduced-motion behavior when editing source.
Use the shared theme tokens. Do not hardcode a palette or radius.

Source

The CLI reuses your shared cn utility. If it is missing, installation creates it at the configured utils path. Existing utilities are checked before a replacement is offered.

These are the files the CLI installs. The control installs one main component file.

<script setup lang="ts">
import type { ThemeControlTransitionProps } from 'uitheme-web/vue';
import { shallowRef } from 'vue';
import { SunIcon, MoonIcon } from '@lucide/vue';
import { useUITheme } from 'uitheme-web/vue';
import ThemeToggle from './theme-toggle.vue';
import { cn } from '@/lib/utils';

const props = withDefaults(
  defineProps<
    ThemeControlTransitionProps & {
      effect?: 'rotate' | 'slide' | 'blur';
      label?: string;
      disabled?: boolean;
      borderStyle?: 'solid' | 'shadow';
      class?: string;
      classes?: Partial<
        Record<
          'root' | 'trigger' | 'content' | 'item' | 'label' | 'track' | 'thumb',
          string
        >
      >;
    }
  >(),
  {
    duration: undefined,
    slideDirection: undefined,
    borderStyle: 'solid',
    class: undefined,
    classes: undefined,
    label: undefined,
    effect: 'rotate',
  }
);

const theme = useUITheme();

const keyboard = shallowRef(false);

const layer =
  'col-start-1 row-start-1 inline-flex size-4 items-center justify-center motion-reduce:!transform-none motion-reduce:!translate-x-0 motion-reduce:!rotate-0 motion-reduce:!scale-100 motion-reduce:!blur-none';

function hidden(side: 'sun' | 'moon') {
  return props.effect === 'slide'
    ? side === 'sun'
      ? '-translate-x-2'
      : 'translate-x-2'
    : props.effect === 'blur'
      ? 'scale-75 blur-[4px]'
      : side === 'sun'
        ? '-rotate-90 scale-75'
        : 'rotate-90 scale-75';
}
</script>
<template>
  <ThemeToggle
    v-bind="props"
    :class="props.class"
    :label="
      label ??
      `Switch to ${theme.resolvedTheme.value === 'dark' ? 'light' : 'dark'} theme`
    "
    :classes="{
      ...props.classes,
      trigger: cn(
        'w-10 px-0 active:scale-[0.96] motion-reduce:active:scale-100',
        props.classes?.trigger
      ),
    }"
    @keydown.capture="keyboard = true"
    @pointerdown.capture="keyboard = false"
  >
    <span
      aria-hidden="true"
      :data-effect="effect"
      class="grid size-4 overflow-hidden"
    >
      <span
        :class="[
          layer,
          keyboard
            ? 'transition-none motion-reduce:transition-none'
            : 'transition-[transform,translate,rotate,scale,opacity,filter] duration-200 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-opacity motion-reduce:duration-100',
          theme.resolvedTheme.value === 'dark'
            ? ['opacity-0', hidden('sun')]
            : 'opacity-100',
        ]"
        ><SunIcon class="size-4"
      /></span>
      <span
        :class="[
          layer,
          keyboard
            ? 'transition-none motion-reduce:transition-none'
            : 'transition-[transform,translate,rotate,scale,opacity,filter] duration-200 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-opacity motion-reduce:duration-100',
          theme.resolvedTheme.value === 'dark'
            ? 'opacity-100'
            : ['opacity-0', hidden('moon')],
        ]"
        ><MoonIcon class="size-4"
      /></span>
    </span>
  </ThemeToggle>
</template>

<script setup lang="ts">
import type { ThemeControlTransitionProps } from 'uitheme-web/vue';
import { SunIcon, MoonIcon } from '@lucide/vue';
import { Toggle } from 'reka-ui';
import { computed } from 'vue';
import { useUITheme } from 'uitheme-web/vue';
import { cn } from '@/lib/utils';

const props = withDefaults(
  defineProps<
    ThemeControlTransitionProps & {
      display?: 'text' | 'icon-text';
      disabled?: boolean;
      borderStyle?: 'solid' | 'shadow';
      class?: string;
      classes?: Partial<
        Record<
          'root' | 'trigger' | 'content' | 'item' | 'label' | 'track' | 'thumb',
          string
        >
      >;
      label?: string;
      lightLabel?: string;
      darkLabel?: string;
    }
  >(),
  {
    duration: undefined,
    slideDirection: undefined,
    display: 'text',
    borderStyle: 'solid',
    class: undefined,
    classes: undefined,
    label: undefined,
    lightLabel: 'Switch to light theme',
    darkLabel: 'Switch to dark theme',
  }
);

const theme = useUITheme(() => ({
  animationType: props.animationType,
  duration: props.duration,
  slideDirection: props.slideDirection,
}));

const target = computed(() =>
  theme.resolvedTheme.value === 'dark' ? 'light' : 'dark'
);

const text = computed(() =>
  target.value === 'light' ? props.lightLabel : props.darkLabel
);

const rootClass = computed(() =>
  cn('inline-flex', props.class, props.classes?.['root'])
);

const triggerClass = computed(() =>
  cn(
    'inline-flex h-10 gap-2 items-center justify-center rounded-md border border-border bg-background px-3 py-2 text-sm font-medium text-foreground transition-colors hover:bg-accent outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 data-[border-style=shadow]:[--shadow-border-edge:theme(colors.border)] data-[border-style=shadow]:[--shadow-border-focus:theme(colors.ring)] data-[border-style=shadow]:border-transparent data-[border-style=shadow]:focus-visible:border-transparent data-[border-style=shadow]:ring-0 data-[border-style=shadow]:focus-visible:ring-0 data-[border-style=shadow]:shadow-[0_0_4px_rgb(0_0_0_/_0.25),inset_0_0_0_1px_var(--shadow-border-edge)] data-[border-style=shadow]:hover:shadow-[0_0_4px_rgb(0_0_0_/_0.25),inset_0_0_0_1px_color-mix(in_oklch,var(--shadow-border-focus)_55%,transparent)] data-[border-style=shadow]:focus-visible:shadow-[0_0_12px_color-mix(in_oklch,var(--shadow-border-focus)_18%,transparent),0_1px_3px_rgb(0_0_0_/_0.1),inset_0_0_0_2px_color-mix(in_oklch,var(--shadow-border-focus)_55%,transparent)] data-[border-style=shadow]:forced-colors:outline data-[border-style=shadow]:forced-colors:outline-1 data-[border-style=shadow]:forced-colors:outline-[CanvasText] data-[border-style=shadow]:forced-colors:focus-visible:outline-2 data-[border-style=shadow]:forced-colors:focus-visible:outline-[Highlight]',
    props.classes?.['trigger']
  )
);
</script>

<template>
  <div :class="rootClass">
    <Toggle
      :model-value="theme.resolvedTheme.value === 'dark'"
      type="button"
      :data-border-style="borderStyle"
      :class="triggerClass"
      :aria-label="label ?? (display === 'text' ? 'Toggle theme' : text)"
      :disabled="disabled || !theme.mounted.value"
      @click="theme.switchTheme(target, $event)"
    >
      <slot>
        <component
          :is="theme.resolvedTheme.value === 'dark' ? MoonIcon : SunIcon"
          v-if="display !== 'text'"
          aria-hidden="true"
          focusable="false"
          class="size-4 shrink-0"
        />
        <span>{{ text }}</span>
      </slot>
    </Toggle>
  </div>
</template>

Dependencies: @lucide/vue

Customization

Use borderStyle="shadow" in React or border-style="shadow" in Vue for prominent shadow borders. The default is solid.

Use slideDirection only when animationType is ThemeAnimationType.SLIDE. Set both props on the control when you need a slide direction override.

Use effect="rotate" (default), effect="slide", or effect="blur" for the icon exchange. Icon motion lasts 200ms and retargets from its current state on another pointer activation. Use animationType, duration, and slideDirection for the separate UI theme transition. Use native button props, label, and classes to customize the control.

PreviewCopy Anchor Link

ExamplesCopy Anchor Link

Theme transition

Shadow borders

Slide icons

Blur icons

When to useCopy Anchor Link

When not to useCopy Anchor Link

InstallationCopy Anchor Link

UsageCopy Anchor Link

API referenceCopy Anchor Link

KeyboardCopy Anchor Link

AccessibilityCopy Anchor Link

Theme behaviorCopy Anchor Link

AI Agent notesCopy Anchor Link

SourceCopy Anchor Link

CustomizationCopy Anchor Link

Preview

Examples

When to use

When not to use

Installation

Usage

API reference

Keyboard

Accessibility

Theme behavior

AI Agent notes

Source

Customization