How to Configure Global Settings in Element UI Using $ELEMENT

Set global component size and z-index defaults in Element UI by defining the $ELEMENT property on the Vue prototype, either through the installation options object or by manual assignment before registering components.

When building Vue applications with Element UI, maintaining consistent component sizing and overlay stacking across your entire application is essential. The library provides a global configuration object called $ELEMENT that stores default values for component size and z-index base values. This object is attached to the Vue prototype during installation, allowing every component in the library to access these defaults without explicit prop declarations.

How $ELEMENT Works in Element UI

During the installation process, Element UI attaches a configuration object to Vue.prototype.$ELEMENT in src/index.js. The install function merges user-provided options with internal defaults:

Vue.prototype.$ELEMENT = {
  size: opts.size || '',
  zIndex: opts.zIndex || 2000
};

Source: src/index.js – lines 194‑196

The size property accepts values like medium, small, or mini, which components use as their default size when no explicit size prop is provided. The zIndex property defaults to 2000 and serves as the base stacking order for overlay components including dialogs, popovers, dropdowns, and tooltips.

Components access these values reactively. For example, the popup manager in src/utils/popup/popup-manager.js retrieves the global z-index when no specific value is supplied:

zIndex = zIndex || (Vue.prototype.$ELEMENT || {}).zIndex || 2000;

Source: src/utils/popup/popup-manager.js – line 158

Configuring Global Component Size and Z-Index

You can define these global settings using two primary approaches depending on your import strategy.

Method 1: During Installation with Vue.use()

When importing the entire Element UI library, pass a configuration object as the second argument to Vue.use():

import Vue from 'vue';
import Element from 'element-ui';

Vue.use(Element, { 
  size: 'small', 
  zIndex: 3000 
});

new Vue({
  el: '#app'
});

This approach automatically assigns the configuration to Vue.prototype.$ELEMENT before any components are instantiated, ensuring consistent defaults across your application.

Method 2: Manual Assignment for Partial Imports

When using tree-shaking to import only specific components, you must manually define $ELEMENT on the Vue prototype before registering components:

import Vue from 'vue';
import { Button, Dialog } from 'element-ui';

// Define global configuration before component registration
Vue.prototype.$ELEMENT = { 
  size: 'small', 
  zIndex: 3000 
};

// Register only the components you need
Vue.use(Button);
Vue.use(Dialog);

Reference: quickstart.md – lines 69‑75

This manual assignment ensures that even partially imported components can access the global size and z-index defaults.

Runtime Configuration Changes

You can modify global settings after initialization, though changes only affect components created or updated after the modification:

// Change default size for all subsequent components
Vue.prototype.$ELEMENT.size = 'mini';

// Increase base z-index for newly opened popups
Vue.prototype.$ELEMENT.zIndex = 2500;

Components that have already mounted will not automatically react to these changes unless they explicitly watch the $ELEMENT object. However, overlay components like dialogs and dropdowns typically check the z-index value each time they open, so runtime z-index changes affect newly displayed overlays immediately.

Summary

• $ELEMENT is a global configuration object attached to Vue.prototype during Element UI installation in src/index.js.
• It stores default values for component size (medium, small, mini) and z-index base (default 2000).
• Configure it by passing options to Vue.use(Element, options) for full imports, or manually assign to Vue.prototype.$ELEMENT before component registration for partial imports.
• Components access these defaults at runtime, with the popup manager in src/utils/popup/popup-manager.js using the z-index fallback for overlay stacking.
• Runtime modifications to $ELEMENT affect components instantiated after the change, making it suitable for dynamic theming scenarios.

Frequently Asked Questions

What values can I set for the global size property?

The size property accepts string values representing Element UI's standard size variants: medium, small, or mini. When set, components like buttons, inputs, and selects that support the size prop will default to this value unless explicitly overridden. An empty string or omitting the property leaves components at their internal default size.

Why is my z-index configuration not affecting existing dialogs?

The global z-index value is typically read when overlay components initialize or open, not continuously watched. Components already mounted in the DOM will not automatically update their stacking order when you modify Vue.prototype.$ELEMENT.zIndex at runtime. To apply new z-index values to existing overlays, you must close and reopen the dialogs, or manually trigger a component update that recalculates the z-index.

Can I use $ELEMENT with partial component imports?

Yes, but you must manually assign the configuration object to Vue.prototype.$ELEMENT before calling Vue.use() on individual components. When using tree-shaking to import specific components like Button or Dialog, the automatic installation hook that sets up $ELEMENT does not run. Assign the object manually as shown in the partial import examples to ensure components can access global size and z-index defaults.

What is the default z-index value if I don't configure $ELEMENT?

If you do not specify a z-index value during installation, Element UI defaults to 2000. This value is hardcoded in the install function within src/index.js and serves as the base stacking order for all overlay components including dialogs, popovers, and dropdowns. The popup manager in src/utils/popup/popup-manager.js falls back to this value when no global configuration is present.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}