Theming

BreezeUI provides flexible theming capabilities. You can quickly configure the theme using the BrConfigProvider component, or have fine-grained control via CSS variables.

Using ConfigProvider (Recommended)

The BrConfigProvider component allows you to dynamically configure the theme at the application root (or any node). It automatically handles color conversion and style injection.

<script setup lang="ts">
import { ref } from 'vue';
import { BrConfigProvider } from '@breezeui/vue';

const theme = ref({
  primary: '#3b82f6', // Supports Hex colors, automatically converted to HSL
  radius: 0.5, // Automatically converted to 0.5rem
  // ...other configurations
});
</script>

<template>
  <BrConfigProvider :theme="theme">
    <App />
  </BrConfigProvider>
</template>

For detailed theme configuration fields, please refer to the API Reference below.

API Reference

BrConfigProvider Props

Prop	Type	Default	Description
theme	ThemeConfig	-	Global theme configuration object
size	ComponentSize	'default'	Global default size for components. Options: xs, sm, md, lg, xl, 2xl
toast	BrToastConfig	-	Global Toast behavior configuration
locale	'en-US' | 'zh-CN'	'en-US'	Global locale configuration. Components use this to display default texts.
tag	string	'div'	The root element tag or component to render

Internationalization (i18n)

You can set a global locale for all components via BrConfigProvider using the locale prop. The default locale is en-US. Currently supported locales are en-US and zh-CN.

<script setup lang="ts">
import { ref } from 'vue';
import { BrConfigProvider, BrSelectDialog } from '@breezeui/vue';

const currentLocale = ref('zh-CN');
</script>

<template>
  <BrConfigProvider :locale="currentLocale">
    <!-- Component will use Chinese texts by default -->
    <BrSelectDialog />
  </BrConfigProvider>
</template>

Note: If you pass emptyText or placeholder to an individual component, it will always override the global locale configuration.

<template>
  <BrConfigProvider locale="zh-CN">
    <!-- Will display "暂无数据" (from global locale) -->
    <BrTable :data="[]" />

    <!-- Will display "Custom empty text" (Component Props have higher priority) -->
    <BrTable :data="[]" emptyText="Custom empty text" />
  </BrConfigProvider>
</template>

ThemeConfig Type Definition

interface ThemeConfig {
  // Base Colors
  background?: string;
  foreground?: string;

  // Functional Colors
  primary?: string;
  primaryForeground?: string;
  secondary?: string;
  secondaryForeground?: string;
  muted?: string;
  mutedForeground?: string;
  accent?: string;
  accentForeground?: string;
  destructive?: string;
  destructiveForeground?: string;
  error?: string;
  errorForeground?: string;
  success?: string;
  successForeground?: string;
  warning?: string;
  warningForeground?: string;
  info?: string;
  infoForeground?: string;
  carbon?: string;
  carbonForeground?: string;

  // Component Backgrounds
  card?: string;
  cardForeground?: string;
  popover?: string;
  popoverForeground?: string;

  // Others
  border?: string;
  input?: string;
  ring?: string;
  radius?: string | number;
  shadow?: string;
  transitionDuration?: string;

  // Z-Index
  zTooltip?: string | number;
  zToast?: string | number;
  zLoading?: string | number;
}

CSS Variables (Advanced)

BreezeUI uses CSS variables under the hood to manage colors and styles, which means you can easily customize the appearance of components to match your brand.

Variable List

Define the following CSS variables in your global CSS file (e.g., style.css or the <style> block in App.vue):

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;

  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;

  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;

  --primary: 239 84% 67%;
  --primary-foreground: 0 0% 100%;

  --secondary: 240 5% 96%;
  --secondary-foreground: 240 6% 10%;

  --muted: 240 5% 96%;
  --muted-foreground: 240 4% 46%;

  --accent: 240 5% 96%;
  --accent-foreground: 240 6% 10%;

  --destructive: 0 84% 60%;
  --destructive-foreground: 0 0% 100%;

  --error: 0 84% 60%;
  --error-foreground: 0 0% 100%;

  --success: 142 71% 45%;
  --success-foreground: 0 0% 100%;

  --warning: 38 92% 50%;
  --warning-foreground: 0 0% 100%;

  --info: 217 91% 60%;
  --info-foreground: 0 0% 100%;

  --carbon: 215 28% 17%;
  --carbon-foreground: 0 0% 100%;

  --border: 214.3 31.8% 85%;
  --input: 214.3 31.8% 85%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.5rem;
  --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
  --z-tooltip: 60;
  --z-toast: 100;
  --z-loading: 50;
  --transition-duration: 300ms;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;

  --card: 222.2 84% 4.9%;
  --card-foreground: 210 40% 98%;

  --popover: 222.2 84% 4.9%;
  --popover-foreground: 210 40% 98%;

  --primary: 239 84% 67%;
  --primary-foreground: 0 0% 100%;

  --secondary: 240 3.7% 15.9%;
  --secondary-foreground: 210 40% 98%;

  --muted: 240 3.7% 15.9%;
  --muted-foreground: 215 20.2% 65.1%;

  --accent: 240 3.7% 15.9%;
  --accent-foreground: 210 40% 98%;

  --destructive: 0 62.8% 30.6%;
  --destructive-foreground: 0 0% 98%;

  --error: 0 62.8% 30.6%;
  --error-foreground: 0 0% 98%;

  --success: 142 70% 50%;
  --success-foreground: 0 0% 100%;

  --warning: 38 92% 50%;
  --warning-foreground: 0 0% 100%;

  --info: 217 91% 60%;
  --info-foreground: 0 0% 100%;

  --carbon: 215 28% 17%;
  --carbon-foreground: 0 0% 100%;

  --border: 240 3.7% 15.9%;
  --input: 240 3.7% 15.9%;
}

Sizing Customization

You can set a global default size for all components via BrConfigProvider, or customize the sizing system (height, padding, font size) via CSS variables.

Global Component Size

You can use the size prop on BrConfigProvider to set a default size for all BreezeUI components within it. This is useful if you want your entire application (or a specific section) to use a smaller or larger base size without setting the size prop on every individual component.

<script setup lang="ts">
import { ref } from 'vue';
import { BrConfigProvider, BrButton, BrInput } from '@breezeui/vue';

const globalSize = ref('sm');
</script>

<template>
  <BrConfigProvider :size="globalSize">
    <!-- Both components will use the 'sm' size by default -->
    <BrButton>Submit</BrButton>
    <BrInput placeholder="Enter your name..." />
  </BrConfigProvider>
</template>

Via CSS Variables

:root {
  /* Default Sizing */
  --br-h-md: 2.5rem; /* h-10 */
  --br-px-md: 1rem; /* px-4 */
  --br-text-md: 0.875rem; /* text-sm */

  /* You can override other sizes as well: xs, sm, lg, xl, 2xl */
}

Dark Mode

BreezeUI's dark mode is based on the CSS class .dark. Simply add the dark class to the html or body element to switch to the dark theme.

<html class="dark">
  <!-- ... -->
</html>

Toggle Example

We recommend using VueUse's useDark and useToggle to easily manage dark mode.

<script setup lang="ts">
import { useDark, useToggle } from '@vueuse/core';
import { BrButton } from '@breezeui/vue';
import { Moon, Sun } from 'lucide-vue-next';

const isDark = useDark();
const toggleDark = useToggle(isDark);
</script>

<template>
  <BrButton variant="outline" size="icon" @click="toggleDark()">
    <Sun v-if="isDark" class="h-[1.2rem] w-[1.2rem]" />
    <Moon v-else class="h-[1.2rem] w-[1.2rem]" />
  </BrButton>
</template>

Dynamic Theme with ConfigProvider

If you use BrConfigProvider to configure your theme, you can switch configurations dynamically based on the current mode using reactive variables.

<script setup lang="ts">
import { computed } from 'vue';
import { useDark } from '@vueuse/core';
import { BrConfigProvider } from '@breezeui/vue';

const isDark = useDark();

// Define configurations for different modes
const theme = computed(() => {
  return isDark.value
    ? {
        // Dark mode configuration
        primary: '#60a5fa', // blue-400
        radius: 0.5,
      }
    : {
        // Light mode configuration
        primary: '#2563eb', // blue-600
        radius: 0.5,
      };
});
</script>

<template>
  <BrConfigProvider :theme="theme">
    <div class="p-10">
      <h1 class="text-2xl font-bold mb-4">Current Mode: {{ isDark ? 'Dark' : 'Light' }}</h1>
      <!-- App content -->
    </div>
  </BrConfigProvider>
</template>

This approach allows you to fully control theme logic in JavaScript, rather than relying solely on CSS variables.