ColorModeButton

ButtonGitHub
A Button to switch between light and dark mode.

Usage

The ColorModeButton component extends the Button component, so you can pass any property such as color, variant, size, etc.

<template>
  <UColorModeButton />
</template>
The button defaults to color="neutral" and variant="ghost".

Examples

With custom icons

Use the app.config.ts to customize the icon with the ui.icons property:

app.config.ts
export default defineAppConfig({
  ui: {
    icons: {
      light: 'i-ph-sun',
      dark: 'i-ph-moon'
    }
  }
})

Use the vite.config.ts to customize the icon with the ui.icons property:

vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        icons: {
          light: 'i-ph-sun',
          dark: 'i-ph-moon'
        }
      }
    })
  ]
})

With fallback slot

As the button is wrapped in a ClientOnly component, you can pass a fallback slot to display a placeholder while the component is loading.

<template>
  <UColorModeButton>
    <template #fallback>
      <UButton loading variant="ghost" color="neutral" />
    </template>
  </UColorModeButton>
</template>

API

Props

Prop Default Type
as'button'any

The element or component this component should render as when not a link.

color'neutral' "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
variant'ghost' "link" | "ghost" | "solid" | "outline" | "soft" | "subtle"
trailingIcon string | object

Display an icon on the right side.

name string
activeboolean

Force the link to be active independent of the current route.

trailingboolean

When true, the icon will be displayed on the right side.

loadingboolean

When true, the loading icon will be displayed.

referrerpolicy "" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url"
icon string | object

Display an icon based on the leading and trailing props.

size'md' "md" | "xs" | "sm" | "lg" | "xl"
avatar AvatarProps

Display an avatar on the left side.

to string | RouteLocationAsRelativeGeneric | RouteLocationAsPathGeneric

Route Location the link should navigate to when clicked on.

autofocus false | true | "true" | "false"
disabledboolean
type'button' "reset" | "submit" | "button"

The type of the button when not a link.

downloadany
hreflang string
media string
ping string
target null | string & {} | "_blank" | "_parent" | "_self" | "_top"

Where to display the linked URL, as the name for a browsing context.

trailingSlash "append" | "remove"

An option to either add or remove trailing slashes in the href for this specific link. Overrides the global trailingSlash option if provided.

label string
activeColor "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
activeVariant "link" | "ghost" | "solid" | "outline" | "soft" | "subtle"
squareboolean

Render the button with equal padding on all sides.

blockboolean

Render the button full width.

loadingAutoboolean

Set loading state automatically based on the @click promise state

leadingboolean

When true, the icon will be displayed on the left side.

leadingIcon string | object

Display an icon on the left side.

loadingIconappConfig.ui.icons.loading string | object

The icon when the loading prop is true.

ui { base?: ClassNameValue; label?: ClassNameValue; leadingIcon?: ClassNameValue; leadingAvatar?: ClassNameValue; leadingAvatarSize?: ClassNameValue; trailingIcon?: ClassNameValue; }
This component also supports all native <button> HTML attributes.

Slots

Slot Type

Changelog

5f30c — fix: missing icon import

1d1c6 — fix: use css to display color mode icon (#5394)

5b177 — feat: extend native HTML attributes (#5348)

5cb65 — feat: import @nuxt/ui-pro components

ColorModeAvatar

An Avatar with a different source for light and dark mode.

ColorModeImage

An image element with a different source for light and dark mode.