Pixel Theme

Starting in v1, Mekari Pixel introduced Design Token v2.4 with built-in light/dark mode capabilities and new usePixelTheme composable function for seamless theme management.

We strongly recommend using the usePixelTheme composable for managing themes. It handles all the complexity for you with:

• Automatic Theme Handling – No need to manually set HTML attributes
• Full Compatibility – Switch seamlessly between Design Token v2.1 and v2.4
• Persistent User Preferences – Theme settings saved in localStorage
• Multi-Tab Support – Proper storage mechanisms for cross-tab synchronization

Prequisites

Ensure you have installed and configured pixelPlugin in your project. Refer to Getting Started - Vue 3 if needed.

Design Token v2.1 vs v2.4

Pixel offers two design token versions. Choose based on your project needs:

Feature	Token v2.1	Token v2.4
Token System	Legacy tokens	Enhanced new tokens
Semantic Token	Not supported	Built-in semantic token system
Dark Mode	Not supported	Built-in dark mode support
Theming System	Not supported	Default & Enterprise
Default Recommendation	Existing projects	New / Migration project

Migration Tip: You can gradually migrate to Token v2.4 per page (see Gradually Apply Token v2.4 section).

Managing Pixel Theme

Enabling Design Token v2.4

By default, Token v2.1 is active. Enable Token v2.4 using the usePixelTheme composable:

import { usePixelTheme } from '@mekari/pixel3'

const { setNextTheme, isNextTheme } = usePixelTheme()

setNextTheme(true) // Enable Design Token v2.4

API Reference:

• setNextTheme(value: boolean) → Toggle between Token versions
• isNextTheme – Boolean indicating whether Token v2.4 is active
  • true → Uses Design Token v2.4
  • false → Uses Design Token v2.1

---

Managing Dark & Light Mode

Design Token v2.4 provides built-in light/dark mode support. Toggle modes effortlessly:

import { usePixelTheme } from '@mekari/pixel3'

const { setNextTheme, setDarkMode, isDark } = usePixelTheme()

setNextTheme(true) // Must Enable Design Token 2.4 first
setDarkMode(true) // Enable Dark Mode

API Reference:

• setDarkMode(value: boolean) – Toggle light/dark mode dynamically
• isDark – Boolean indicating if dark mode is active

---

Setting Product Theme (Enterprise)

By default, Design Token v2.4 don't use product-specific themes, but if you want to add product themes like "enterprise" for different visual identities. Set your product theme as follows:

import { usePixelTheme } from '@mekari/pixel3'

const { setNextTheme, setProductTheme, getProductTheme } = usePixelTheme()

setNextTheme(true) // Must Enable Design Token v2.4 first
setProductTheme('enterprise') // Set enterprise theme

API Reference:

• setProductTheme(product: 'enterprise' | '') – Set the product theme variant
• getProductTheme() – Returns the current product theme identifier

Implementation Examples

Globally Apply Token v2.4

Enable Token v2.4 globally and toggle dark mode using the usePixelTheme composable:

Gradually Apply Token v2.4

Migrate to Token v2.4 incrementally by enabling it only on specific pages or components:

import { usePixelTheme } from '@mekari/pixel3'
import { useRoute } from 'vue-router'

const route = useRoute()
const { setNextTheme, setDarkMode } = usePixelTheme()

watchEffect(() => {
  // Enable Token v2.4 only on /inbox page
  setNextTheme(route.path === '/inbox')
  setDarkMode(false)
})

Manually Apply Token v2.4

While we recommend using usePixelTheme, you can also perform manual DOM manipulation:

WARNING

Always keep isNextTheme in sync when handling themes manually.

• Set isNextTheme = true when data-panda-theme="next" is applied
• Set isNextTheme = false when data-panda-theme="next" is removed

Mismatched states may result in incorrect component's styling.

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

onMounted(() => {
  // Manual apply
  applyNextTheme()
  showLightMode()
})

usePixelTheme API

You can use the following APIs from the usePixelTheme composable:

Task	API	Example
Set Token v2.4	setNextTheme(boolean)	setNextTheme(true)
Get Token Version	isNextTheme	const isUseNextTheme = isNextTheme.value
Set Dark Mode	setDarkMode(boolean)	setDarkMode(true)
Get Dark Version	isDark	const isDarkMode = isDark.value
Set Product Theme	setProductTheme(string)	setProductTheme('enterprise')
Get Product Theme	getProductTheme()	const theme = getProductTheme()
Activate Watcher	activePixelThemeWatcher()	Called automatically by pixelPlugin
Stop Watcher	stopPixelThemeWatcher()	stopPixelThemeWatcher()