tessl/npm-element-plus

A Component Library for Vue 3

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Theming and Customization

Name: tessl/npm-element-plus
Author: tessl

Comprehensive theming system with CSS custom properties, SCSS variables, and dark mode support for complete design control.

Capabilities

Global Configuration

Configure Element Plus globally with theming options.

declare const ElConfigProvider: Component;

interface ConfigProviderProps {
  /** Component size configuration */
  size?: ComponentSize;
  /** Z-index configuration */
  zIndex?: number;
  /** Locale configuration */
  locale?: Language;
  /** Namespace configuration for CSS classes */
  namespace?: string;
  /** Message configuration */
  message?: MessageConfig;
  /** Button configuration */
  button?: ButtonConfig;
  /** Experimental features */
  experimentalFeatures?: ExperimentalFeatures;
}

interface MessageConfig {
  /** Maximum number of messages */
  max?: number;
}

interface ButtonConfig {
  /** Auto insert space between characters */
  autoInsertSpace?: boolean;
}

interface ExperimentalFeatures {
  /** Draw border */
  drawBorder?: boolean;
}

Usage Example:

<template>
  <el-config-provider :namespace="namespace" :locale="locale" :size="size">
    <App />
  </el-config-provider>
</template>

<script setup>
import { ElConfigProvider } from 'element-plus';
import zhCn from 'element-plus/dist/locale/zh-cn.mjs';

const namespace = 'ep';
const locale = zhCn;
const size = 'default';
</script>

CSS Custom Properties

Element Plus uses CSS custom properties for theming.

interface ThemeVars {
  /** Primary color */
  '--el-color-primary'?: string;
  /** Success color */
  '--el-color-success'?: string;
  /** Warning color */
  '--el-color-warning'?: string;
  /** Danger color */
  '--el-color-danger'?: string;
  /** Error color */
  '--el-color-error'?: string;
  /** Info color */
  '--el-color-info'?: string;
  
  /** Text colors */
  '--el-text-color-primary'?: string;
  '--el-text-color-regular'?: string;
  '--el-text-color-secondary'?: string;
  '--el-text-color-placeholder'?: string;
  '--el-text-color-disabled'?: string;
  
  /** Border colors */
  '--el-border-color'?: string;
  '--el-border-color-light'?: string;
  '--el-border-color-lighter'?: string;
  '--el-border-color-extra-light'?: string;
  '--el-border-color-dark'?: string;
  '--el-border-color-darker'?: string;
  
  /** Background colors */
  '--el-bg-color'?: string;
  '--el-bg-color-page'?: string;
  '--el-bg-color-overlay'?: string;
  
  /** Fill colors */
  '--el-fill-color'?: string;
  '--el-fill-color-light'?: string;
  '--el-fill-color-lighter'?: string;
  '--el-fill-color-extra-light'?: string;
  '--el-fill-color-dark'?: string;
  '--el-fill-color-darker'?: string;
  '--el-fill-color-blank'?: string;
  
  /** Font family */
  '--el-font-family'?: string;
  
  /** Font sizes */
  '--el-font-size-extra-large'?: string;
  '--el-font-size-large'?: string;
  '--el-font-size-medium'?: string;
  '--el-font-size-base'?: string;
  '--el-font-size-small'?: string;
  '--el-font-size-extra-small'?: string;
  
  /** Component sizes */
  '--el-component-size-large'?: string;
  '--el-component-size'?: string;
  '--el-component-size-small'?: string;
  
  /** Border radius */
  '--el-border-radius-base'?: string;
  '--el-border-radius-small'?: string;
  '--el-border-radius-round'?: string;
  '--el-border-radius-circle'?: string;
}

Usage Example:

:root {
  --el-color-primary: #409eff;
  --el-color-success: #67c23a;
  --el-color-warning: #e6a23c;
  --el-color-danger: #f56c6c;
  --el-color-info: #909399;
}

/* Dark mode */
html.dark {
  --el-bg-color: #141414;
  --el-text-color-primary: #e5eaf3;
  --el-text-color-regular: #cfd3dc;
  --el-text-color-secondary: #a3a6ad;
}

Dark Mode

Built-in dark mode support through CSS custom properties.

/**
 * Toggle dark mode
 * @param isDark - Whether to enable dark mode
 */
declare function useDark(): {
  isDark: Ref<boolean>;
  toggleDark: () => void;
};

Usage Example:

<template>
  <el-switch v-model="isDark" @change="toggleDark" />
</template>

<script setup>
import { useDark } from '@vueuse/core';

const { isDark, toggleDark } = useDark({
  selector: 'html',
  attribute: 'class',
  valueDark: 'dark',
  valueLight: 'light',
});
</script>

SCSS Variables

SCSS variables for advanced customization.

interface SCSSVariables {
  /** Namespace */
  $namespace?: string;
  
  /** Color palette */
  $colors?: {
    primary?: string;
    success?: string;
    warning?: string;
    danger?: string;
    error?: string;
    info?: string;
  };
  
  /** Common variables */
  $common?: {
    $border-style?: string;
    $border-width?: string;
    $border-color?: string;
    $border-radius-base?: string;
    $border-radius-small?: string;
    $border-radius-round?: string;
    $border-radius-circle?: string;
  };
  
  /** Typography */
  $font?: {
    $font-size-extra-large?: string;
    $font-size-large?: string;
    $font-size-medium?: string;
    $font-size-base?: string;
    $font-size-small?: string;
    $font-size-extra-small?: string;
    $font-family?: string;
    $font-weight-primary?: number;
  };
  
  /** Z-index */
  $z-index?: {
    $z-index-normal?: number;
    $z-index-top?: number;
    $z-index-popper?: number;
  };
  
  /** Component sizes */
  $component-size?: {
    $component-size-large?: string;
    $component-size-default?: string;
    $component-size-small?: string;
  };
}

Custom Theme Generation

Generate custom themes programmatically.

/**
 * Generate theme CSS variables from color palette
 * @param colors - Base color configuration
 * @returns CSS variables object
 */
declare function generateTheme(colors: ThemeColors): ThemeVars;

interface ThemeColors {
  /** Primary brand color */
  primary?: string;
  /** Success state color */
  success?: string;
  /** Warning state color */
  warning?: string;
  /** Danger/error state color */
  danger?: string;
  /** Information state color */
  info?: string;
}

/**
 * Get color variations (light/dark) for a base color
 * @param color - Base color hex value
 * @returns Color variations object
 */
declare function getColorVariations(color: string): ColorVariations;

interface ColorVariations {
  'color-primary'?: string;
  'color-primary-light-1'?: string;
  'color-primary-light-2'?: string;
  'color-primary-light-3'?: string;
  'color-primary-light-4'?: string;
  'color-primary-light-5'?: string;
  'color-primary-light-6'?: string;
  'color-primary-light-7'?: string;
  'color-primary-light-8'?: string;
  'color-primary-light-9'?: string;
  'color-primary-dark-1'?: string;
  'color-primary-dark-2'?: string;
}

Namespace Customization

Customize CSS class namespace to avoid conflicts.

/**
 * Set global namespace for Element Plus components
 * @param namespace - Custom namespace prefix
 */
declare function setNamespace(namespace: string): void;

/**
 * Get current namespace configuration
 * @returns Current namespace
 */
declare function getNamespace(): string;

Usage Example:

import { setNamespace } from 'element-plus';

// Change default 'el' namespace to 'ep'
setNamespace('ep');

// Components will now use 'ep-button', 'ep-input', etc.

Component-Specific Theming

Individual component theming options.

interface ComponentTheme {
  /** Button theming */
  button?: {
    '--el-button-font-weight'?: string;
    '--el-button-border-color'?: string;
    '--el-button-bg-color'?: string;
    '--el-button-text-color'?: string;
    '--el-button-disabled-text-color'?: string;
    '--el-button-disabled-bg-color'?: string;
    '--el-button-disabled-border-color'?: string;
    '--el-button-divide-border-color'?: string;
    '--el-button-hover-text-color'?: string;
    '--el-button-hover-bg-color'?: string;
    '--el-button-hover-border-color'?: string;
    '--el-button-active-text-color'?: string;
    '--el-button-active-border-color'?: string;
    '--el-button-active-bg-color'?: string;
  };
  
  /** Input theming */
  input?: {
    '--el-input-text-color'?: string;
    '--el-input-border'?: string;
    '--el-input-hover-border'?: string;
    '--el-input-focus-border'?: string;
    '--el-input-transparent-border'?: string;
    '--el-input-border-color'?: string;
    '--el-input-border-radius'?: string;
    '--el-input-bg-color'?: string;
    '--el-input-icon-color'?: string;
    '--el-input-placeholder-color'?: string;
    '--el-input-hover-border-color'?: string;
    '--el-input-clear-hover-color'?: string;
    '--el-input-focus-border-color'?: string;
  };
}

Responsive Theming

Responsive breakpoint system for theming.

interface Breakpoints {
  xs?: string; // <576px
  sm?: string; // ≥576px
  md?: string; // ≥768px
  lg?: string; // ≥992px
  xl?: string; // ≥1200px
  xxl?: string; // ≥1920px
}

interface ResponsiveTheme {
  /** Breakpoint definitions */
  breakpoints?: Breakpoints;
  /** Responsive spacing */
  spacing?: {
    xs?: string;
    sm?: string;
    md?: string;
    lg?: string;
    xl?: string;
  };
  /** Responsive typography */
  typography?: {
    xs?: { fontSize?: string; lineHeight?: string };
    sm?: { fontSize?: string; lineHeight?: string };
    md?: { fontSize?: string; lineHeight?: string };
    lg?: { fontSize?: string; lineHeight?: string };
    xl?: { fontSize?: string; lineHeight?: string };
  };
}

Types

type ComponentSize = '' | 'large' | 'default' | 'small';

interface Language {
  name: string;
  el: Record<string, any>;
}

interface Component {
  name?: string;
  props?: Record<string, any>;
  emits?: string[] | Record<string, any>;
  setup?: Function;
}

interface Ref<T> {
  value: T;
}

Install with Tessl CLI