@awal-solution/tailwind-theming
v0.0.5
Published
<div align="left"> <h1>Tailwind theming</h1> <p>The <b>TailwindCSS Multi-Theming Plugin</b> is a utility for creating and managing multiple themes in your TailwindCSS-based projects. With this library, you can define, add, update, and remove themes dyn
Downloads
274
Maintainers
Readme
Features:
- Dynamic Theme Management:
- Add, update, and remove themes programmatically.
- Flexible Theme Configuration:
- Define themes using
extend
to seamlessly integrate with TailwindCSS.
- Define themes using
- Data Attributes Selectors:
- Apply themes via
data-theme
attributes.
- Apply themes via
- Default Theme Support:
- Specify a default theme to be applied globally.
- Customizable Media Queries:
- Apply themes based on user preferences, such as dark mode.
Installation:
Install the package via your package manager:
yarn add @awal-solution/tailwind-theming
# or
npm install @awal-solution/tailwind-theming
Getting Started:
1. Configure TailwindCSS Plugin
Add the themePlugin
to your TailwindCSS configuration:
// tailwind.config.js|ts
import { themePlugin } from '@awal-solution/tailwind-theming'
export default {
content: ['./src/**/*.{html,js,ts}'],
plugins: [themePlugin()],
}
2. Initialize Themes in Your Application
Create a ThemeManager
instance and define your themes:
import { ThemeManager } from '@awal-solution/tailwind-theming'
const themeManager = new ThemeManager({
themes: {
'light-theme': {
colors: {
background: { DEFAULT: '#FFFFFF' },
foreground: { DEFAULT: '#000000' },
primary: { DEFAULT: '#0000FF', light: '#0096FF' },
},
},
'dark-theme': {
colors: {
background: { DEFAULT: '#000000' },
foreground: { DEFAULT: '#FFFFFF' },
primary: { DEFAULT: '#0000FF', light: '#0096FF' },
},
},
},
defaultTheme: 'light-theme',
})
export { themeManager }
3. Apply Themes
Use the generated selectors to toggle themes in your application:
// Apply the default theme
document.documentElement.setAttribute('data-theme', 'light-theme')
// Toggle between themes
function toggleTheme() {
const currentTheme = document.documentElement.getAttribute('data-theme')
const newTheme = currentTheme === 'light-theme' ? 'dark-theme' : 'light-theme'
document.documentElement.setAttribute('data-theme', newTheme)
}
API Reference
ThemeManager
Constructor
constructor({ themes: Record<string, Theme>, defaultTheme?: string });
themes
: A record of theme names and their configurations.defaultTheme
: (Optional) The default theme to apply initially.
Methods
get()
Returns all themes, including the default theme and additional themes.
themeManager.get()
getThemeSelectors()
Returns an object containing theme names and their associated selectors.
themeManager.getThemeSelectors()
add(theme: AddThemeType)
Adds a new theme to the existing themes.
themeManager.add({
name: 'custom-theme',
selectors: ['[data-theme="custom-theme"]'],
theme: {
colors: {
background: { DEFAULT: '#555' },
},
},
})
update(themeName: string, properties: Partial<TailwindExtension>)
Updates an existing theme's configuration.
themeManager.update('custom-theme', {
colors: {
primary: { DEFAULT: '#FF0000' },
},
})
remove(themeName: string)
Removes an existing theme by name.
themeManager.remove('custom-theme')
Plugin Options
The themePlugin
provides the following options:
defaultTheme
: (Optional) Default theme configuration.themes
: An array of theme configurations.
Example usage in TailwindCSS:
import { themePlugin } from '@awal-solution/tailwind-theming'
import { themeManager } from './themeManager'
export default {
content: ['./src/**/*.{html,js,ts}'],
plugins: [themePlugin(themeManager.get())],
}
Example CSS:
@tailwind base;
@tailwind components;
@tailwind utilities;
Example
An example setup for toggling themes in your app:
import './index.css'
import { storage } from './storage'
import { themeManager } from './themeManager'
let themeNames = themeManager.getThemeSelectors()
let currentTheme = storage.get<string>('APP_THEME') ?? Object.keys(themeNames)[0]
const initializeApp = () => {
const root = document.documentElement
// Apply the saved theme or system theme as default
root.className = currentTheme
root.setAttribute('data-theme', currentTheme)
storage.set('APP_THEME', currentTheme)
}
const toggleTheme = () => {
const root = document.documentElement
const themeKeys = Object.keys(themeNames)
const currentIndex = themeKeys.findIndex((key) => key === currentTheme)
// Determine the next theme
const nextIndex = (currentIndex + 1) % themeKeys.length
currentTheme = themeKeys[nextIndex]
// Apply the new theme
root.className = currentTheme
root.setAttribute('data-theme', currentTheme)
storage.set('APP_THEME', currentTheme)
// Update button text to show the next theme
const button = document.querySelector<HTMLButtonElement>('#theme-toggle')
if (button) {
const nextTheme = themeNames[themeKeys[(nextIndex + 1) % themeKeys.length]].name
button.textContent = `Switch to ${nextTheme.charAt(0).toUpperCase() + nextTheme.slice(1)} Mode`
}
}
const renderApp = () => {
const app = document.querySelector<HTMLDivElement>('#app')
if (!app) return
app.innerHTML = `
<div class="min-h-screen flex gap-4 items-center justify-center bg-background text-foreground">
<button id="theme-toggle" class="px-4 py-2 bg-primary text-white rounded">
Switch to ${Object.keys(themeNames)[0]} Mode
</button>
<h1 class="border-b border-divider">
Hello, TailwindCSS Theme Toggling!
</h1>
</div>
`
// Attach event listener for the theme toggle button
const button = document.querySelector<HTMLButtonElement>('#theme-toggle')
if (button) {
button.addEventListener('click', toggleTheme)
}
}
initializeApp()
renderApp()
License
This library is open-source and licensed under the MIT License.
Contributions
Contributions are welcome! If you find a bug or want to suggest a feature, please open an issue or submit a pull request.
Happy coding! 🎉