https://github.com/awalsolution/tailwing-theming
https://github.com/awalsolution/tailwing-theming
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/awalsolution/tailwing-theming
- Owner: awalsolution
- License: mit
- Created: 2024-12-04T20:55:22.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-04T17:08:23.000Z (over 1 year ago)
- Last Synced: 2025-10-05T03:59:06.529Z (9 months ago)
- Language: TypeScript
- Size: 117 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Tailwind theming
The TailwindCSS Multi-Theming Plugin 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 dynamically while keeping your configuration clean and extensible.
## Features:
- **Dynamic Theme Management**:
- Add, update, and remove themes programmatically.
- **Flexible Theme Configuration**:
- Define themes using `extend` to seamlessly integrate with TailwindCSS.
- **Data Attributes Selectors**:
- Apply themes via `data-theme` attributes.
- **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:
```bash
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:
```javascript
// 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:
```typescript
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:
```typescript
// 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
```typescript
constructor({ themes: Record, 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.
```typescript
themeManager.get()
```
##### **`getThemeSelectors()`**
Returns an object containing theme names and their associated selectors.
```typescript
themeManager.getThemeSelectors()
```
##### **`add(theme: AddThemeType)`**
Adds a new theme to the existing themes.
```typescript
themeManager.add({
name: 'custom-theme',
selectors: ['[data-theme="custom-theme"]'],
theme: {
colors: {
background: { DEFAULT: '#555' },
},
},
})
```
##### **`update(themeName: string, properties: Partial)`**
Updates an existing theme's configuration.
```typescript
themeManager.update('custom-theme', {
colors: {
primary: { DEFAULT: '#FF0000' },
},
})
```
##### **`remove(themeName: string)`**
Removes an existing theme by name.
```typescript
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:
```javascript
import { themePlugin } from '@awal-solution/tailwind-theming'
import { themeManager } from './themeManager'
export default {
content: ['./src/**/*.{html,js,ts}'],
plugins: [themePlugin(themeManager.get())],
}
```
---
Example CSS:
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```
## Example
An example setup for toggling themes in your app:
```typescript
import './index.css'
import { storage } from './storage'
import { themeManager } from './themeManager'
let themeNames = themeManager.getThemeSelectors()
let currentTheme = storage.get('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('#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('#app')
if (!app) return
app.innerHTML = `
Switch to ${Object.keys(themeNames)[0]} Mode
Hello, TailwindCSS Theme Toggling!
`
// Attach event listener for the theme toggle button
const button = document.querySelector('#theme-toggle')
if (button) {
button.addEventListener('click', toggleTheme)
}
}
initializeApp()
renderApp()
```
---
## License
This library is open-source and licensed under the [MIT License](./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.
## Commits
### Patch release
```bash
fix(theme): correct issue with theme manager
```
### Minor release
```bash
feat(utils): add utility functions for theming
```
### Major release
```bash
fix!: update API endpoints (BREAKING CHANGE: endpoint changes)
```
---
Happy coding! 🎉
---