Pixel Theme

Starting in v1.0.0, we've introduced Design Token v2.4, bringing built-in light/dark mode capabilities and an enhanced usePixelTheme composable for seamless theme management.

While you can manually handle HTML attributes for theming, we strongly recommend using usePixelTheme for its key benefits:

✅ Automatic Theme Handling – No need to manually set HTML attributes.

✅ Full Compatibility – Effortlessly switch between Design Token v2.1 and Design Token v2.4.

✅ Persistent User Preferences – Theme settings are saved in local storage.

✅ Clean & Type-Safe API – Simplifies theme management with intuitive methods.

📌 Prerequisites

Before proceeding, ensure that you have installed and configured PixelPlugin in your project. If you haven't done so, please refer to the Getting Started - Vue 3.

🌟 Enabling Design Token 2.4

By default, Token 2.1 is applied. To enable Token 2.4, use the following API:

import { usePixelTheme } from '@mekari/pixel3'

const { isNextTheme, setNextTheme } = usePixelTheme()

setNextTheme(true)  // Enable Design Token v2.4
setNextTheme(false) // Revert to Design Token v2.1

🔹 API Reference

• isNextTheme → A boolean indicating whether Token 2.4 is active.
  • true → The theme uses Design Token v2.4.
  • false → The theme remains on Design Token v2.1.
• setNextTheme(value: boolean) → A function to toggle between Token 2.1 and Token 2.4.

🌕 Managing Dark & Light Mode

Mekari Pixel provides a built-in dark mode system, allowing you to toggle between light and dark themes effortlessly.

🔹 Usage

import { usePixelTheme } from '@mekari/pixel3'

const { isDark, setDarkMode } = usePixelTheme()

setDarkMode(true)  // Enable Dark Mode
setDarkMode(false) // Enable Light Mode

🔹 API Reference

• isDark → A boolean indicating whether dark mode is active.
• setDarkMode(value: boolean) → A function to toggle light/dark mode dynamically.

Pro Tip: You can combine Token 2.4 with dark mode for an adaptive UI experience.

💻 Implementations

🌍 Globally Apply Token 2.4

By default, Token 2.1 is active. You can globally enable Token 2.4 and toggle dark mode using the usePixelTheme composable.

⚡ Gradually Apply Token 2.4

You can enable Token 2.4 only for specific pages or components instead of applying it globally.

🔹 Example: Enable Token 2.4 only on /inbox page

import { usePixelTheme } from "@mekari/pixel3-utils"; // Ensure the package is installed
const { setNextTheme, setDarkMode } = usePixelTheme();
watchEffect(() => {
  // Apply next theme (Design Token v2.4) only for path inbox.
  setNextTheme(route.path === "/inbox");
  setDarkMode(false);
});

🔧 Manually Handle Theme Changes

While we recommend using the usePixelTheme composable for seamless theme management, manual handling is also possible.

1. Disable Built-in Theme Management:

import { PixelPlugin, type PixelPluginConfig } from '@mekari/pixel3'

const app = createApp(App)
app.use(PixelPlugin, { pixelTheme: false } as PixelPluginConfig)
app.mount('#app')

2. Implement Custom Theme Handling

WARNING

⚠ Important: Always keep isNextTheme in sync when handling themes manually.

• isNextTheme = true when data-panda-theme="next" is set.
• isNextTheme = false when data-panda-theme="next" is not set.
• Mismatched states may result in incorrect component styling.

Example: Manually Setting Themes

import { usePixelTheme } from '@mekari/pixel3'

const { setNextTheme } = usePixelTheme()

function showLightMode() {
  document.documentElement.classList.add('light')
  document.documentElement.classList.remove('dark')
}
function showDarkMode() {
  document.documentElement.classList.add('dark')
  document.documentElement.classList.remove('light')
}
function applyNextTheme() {
  document.documentElement.setAttribute('data-panda-theme', 'next')

  setNextTheme(true)
}
function removeNextTheme() {
  document.documentElement.removeAttribute('data-panda-theme')

  setNextTheme(false)
}