or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

composables.mddata-display-components.mdfeedback-components.mdform-components.mdindex.mdinstallation.mdlayout-components.mdnavigation-components.mdtheming.mdutility-components.md
tile.json

theming.mddocs/

Theming and Customization

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