@qql1/unocss-preset-elementplus

v1.0.5

Published

7 months ago

UnoCSS preset for Element Plus CSS variables and design tokens integration

0High
0Medium
0Low

qql1

unocss element-plus preset css utility-first vue

UnoCSS Preset Element Plus

A UnoCSS preset that provides comprehensive support for Element Plus CSS variables and design tokens, allowing seamless integration between UnoCSS utility classes and Element Plus components.

Features

🎨 Complete Element Plus Color System - Access all Element Plus color variables through UnoCSS utilities
🌗 Theme Support - Full support for light/dark theme variables
📦 Zero Configuration - Works out of the box with Element Plus
🔧 Flexible Options - Customizable prefix and feature toggles
💡 Intelligent IntelliSense - Full TypeScript support with proper type definitions
🎯 Optimized Bundle - Tree-shakeable with minimal runtime overhead

Installation

npm install @qql1/unocss-preset-elementplus
# or
pnpm add @qql1/unocss-preset-elementplus
# or
yarn add @qql1/unocss-preset-elementplus

Usage

Basic Setup

Add the preset to your UnoCSS configuration:

// unocss.config.ts
import { defineConfig } from 'unocss'
import { presetElementPlus } from '@qql1/unocss-preset-elementplus'

export default defineConfig({
  presets: [
    // ... other presets
    presetElementPlus()
  ]
})

With Options

import { defineConfig } from 'unocss'
import { presetElementPlus } from '@qql1/unocss-preset-elementplus'

export default defineConfig({
  presets: [
    presetElementPlus({
      prefix: 'el-',                    // Add prefix to utilities
      includeColorVariants: true,      // Include light/dark color variants
      includeShadows: true             // Include shadow utilities
    })
  ]
})

Using Shortcuts

The preset includes predefined shortcuts for common Element Plus patterns:

import { defineConfig } from 'unocss'
import { presetElementPlus, elementPlusShortcuts } from '@qql1/unocss-preset-elementplus'

export default defineConfig({
  presets: [
    presetElementPlus()
  ],
  shortcuts: [
    ...elementPlusShortcuts
  ]
})

Available Utilities

Color System

Theme Colors

<!-- Background Colors -->
<div class="bg-primary">Primary background</div>
<div class="bg-success">Success background</div>
<div class="bg-warning">Warning background</div>
<div class="bg-danger">Danger background</div>
<div class="bg-info">Info background</div>

<!-- Text Colors -->
<span class="text-primary">Primary text</span>
<span class="text-success">Success text</span>

<!-- Border Colors -->
<div class="border border-primary">Primary border</div>

Color Variants

<!-- Light variants (1-9) -->
<div class="bg-primary-light-3">Light primary</div>
<div class="text-success-light-5">Light success text</div>

<!-- Dark variants (1-2) -->
<div class="bg-warning-dark-2">Dark warning</div>
<div class="border-danger-dark-1">Dark danger border</div>

Opacity Variants

支持所有颜色的透明度变体，使用 /{opacity} 语法，透明度值为 0-100 的整数：

<!-- Background colors with opacity -->
<div class="bg-primary/30">30% 透明度的主色背景</div>
<div class="bg-success/50">50% 透明度的成功色背景</div>
<div class="bg-white/20">20% 透明度的白色背景</div>

<!-- Text colors with opacity -->
<span class="text-primary/80">80% 透明度的主色文字</span>
<span class="text-danger/60">60% 透明度的危险色文字</span>
<span class="text-regular/70">70% 透明度的常规文字</span>

<!-- Border colors with opacity -->
<div class="border border-primary/40">40% 透明度的主色边框</div>
<div class="border border-light/50">50% 透明度的浅色边框</div>

<!-- Color variants with opacity -->
<div class="bg-primary-light-3/50">50% 透明度的浅主色背景</div>
<div class="text-success-dark-2/70">70% 透明度的深成功色文字</div>

<!-- Fill colors with opacity -->
<div class="bg-fill/30">30% 透明度的填充色背景</div>
<div class="bg-fill-light/40">40% 透明度的浅填充色背景</div>

System Colors

<!-- Text System Colors -->
<p class="text-regular">Regular text</p>
<p class="text-secondary">Secondary text</p>
<p class="text-placeholder">Placeholder text</p>
<p class="text-disabled">Disabled text</p>

<!-- Background System Colors -->
<div class="bg-default">Default background</div>
<div class="bg-page">Page background</div>
<div class="bg-overlay">Overlay background</div>

<!-- Border System Colors -->
<div class="border border-light">Light border</div>
<div class="border border-lighter">Lighter border</div>
<div class="border border-extra-light">Extra light border</div>

Fill Colors

<!-- Fill color backgrounds -->
<div class="bg-fill">Default fill</div>
<div class="bg-fill-light">Light fill</div>
<div class="bg-fill-lighter">Lighter fill</div>
<div class="bg-fill-extra-light">Extra light fill</div>
<div class="bg-fill-dark">Dark fill</div>
<div class="bg-fill-darker">Darker fill</div>
<div class="bg-fill-blank">Blank fill</div>

Gradient Utilities

Theme Color Gradients

<!-- Basic gradients -->
<div class="bg-gradient-to-r from-primary to-success">
  Primary to success gradient
</div>

<!-- With color variants -->
<div class="bg-gradient-to-br from-primary-light-3 via-success to-warning-dark-1">
  Complex gradient with variants
</div>

<!-- Fill color gradients -->
<div class="bg-gradient-to-t from-fill-light to-fill-darker">
  Fill gradient
</div>

Shadow Utilities

<!-- Element Plus shadows -->
<div class="shadow-base">Base shadow</div>
<div class="shadow-light">Light shadow</div>
<div class="shadow-lighter">Lighter shadow</div>
<div class="shadow-dark">Dark shadow</div>

State Utilities

<!-- Disabled states -->
<div class="bg-disabled text-disabled border-disabled">
  Disabled element
</div>

<!-- Overlay and mask -->
<div class="bg-overlay">Overlay background</div>
<div class="bg-mask">Mask background</div>

Predefined Shortcuts

The preset includes shortcuts for common Element Plus component patterns:

<!-- Card-like appearance -->
<div class="el-card">Card styled element</div>

<!-- Button styles -->
<button class="el-button-primary">Primary Button</button>
<button class="el-button-success">Success Button</button>
<button class="el-button-warning">Warning Button</button>
<button class="el-button-danger">Danger Button</button>

<!-- Input styles -->
<input class="el-input" placeholder="Enter text">
<input class="el-input-disabled" disabled>

Configuration Options

PresetElementPlusOptions

interface PresetElementPlusOptions {
  /**
   * Prefix for utility classes
   * @default ''
   */
  prefix?: string
  
  /**
   * Whether to include color variant utilities (light/dark levels)
   * @default true
   */
  includeColorVariants?: boolean
  
  /**
   * Whether to include shadow utilities
   * @default true
   */
  includeShadows?: boolean
}

Element Plus Integration

This preset is designed to work seamlessly with Element Plus. Make sure you have Element Plus CSS variables available in your project:

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css' // This provides the CSS variables
import 'uno.css' // Your UnoCSS styles

const app = createApp(App)
app.use(ElementPlus)
app.mount('#app')

Examples

Complete Component Example

<template>
  <div class="el-card">
    <h2 class="text-primary text-xl font-bold mb-4">Settings Panel</h2>
    
    <div class="space-y-4">
      <div class="bg-fill-light p-4 rounded">
        <label class="text-regular text-sm">Username</label>
        <input 
          class="el-input mt-1 w-full" 
          placeholder="Enter username"
        >
      </div>
      
      <div class="flex gap-2">
        <button class="el-button-primary">Save</button>
        <button class="el-button-danger">Cancel</button>
      </div>
    </div>
    
    <!-- Status indicators with variants -->
    <div class="mt-6 space-y-2">
      <div class="bg-success-light-9 text-success p-2 rounded text-sm">
        ✓ Profile updated successfully
      </div>
      
      <div class="bg-warning-light-9 text-warning p-2 rounded text-sm">
        ⚠ Please verify your email
      </div>
    </div>
  </div>
</template>

Theme-Aware Components

<template>
  <div class="min-h-screen bg-page">
    <!-- Header with theme colors -->
    <header class="bg-default border-b border-light p-4">
      <h1 class="text-primary text-2xl font-bold">My App</h1>
    </header>
    
    <!-- Content area -->
    <main class="p-6">
      <div class="bg-default shadow-base rounded-lg p-6">
        <p class="text-regular">
          This content automatically adapts to light/dark themes
          using Element Plus CSS variables.
        </p>
        
        <!-- Interactive elements -->
        <div class="mt-4 space-x-2">
          <span class="bg-primary-light-9 text-primary px-2 py-1 rounded text-sm">
            Primary Tag
          </span>
          <span class="bg-success-light-9 text-success px-2 py-1 rounded text-sm">
            Success Tag  
          </span>
        </div>
      </div>
    </main>
  </div>
</template>

CSS Variables Reference

This preset provides access to all Element Plus CSS variables:

Colors: --el-color-primary, --el-color-success, etc.
Text: --el-text-color-primary, --el-text-color-regular, etc.
Backgrounds: --el-bg-color, --el-bg-color-page, etc.
Borders: --el-border-color, --el-border-color-light, etc.
Fill: --el-fill-color, --el-fill-color-light, etc.
Shadows: --el-box-shadow, --el-box-shadow-light, etc.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License

UnoCSS - The instant on-demand atomic CSS engine
Element Plus - Vue 3 UI library