# How to Configure Global Settings in Element UI Using $ELEMENT

> Configure Element UI global settings like size and z-index by defining $ELEMENT on Vue prototype. Learn how to customize components easily and efficiently.

- Repository: [饿了么前端/element](https://github.com/ElemeFE/element)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/ElemeFE/element/blob/main/src/index.js). The install function merges user-provided options with internal defaults:

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

```

*Source: [src/index.js – lines 194‑196](https://github.com/ElemeFE/element/blob/dev/src/index.js#L194-L196)*

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`](https://github.com/ElemeFE/element/blob/main/src/utils/popup/popup-manager.js) retrieves the global z-index when no specific value is supplied:

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

```

*Source: [src/utils/popup/popup-manager.js – line 158](https://github.com/ElemeFE/element/blob/dev/src/utils/popup/popup-manager.js#L158)*

## 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()`:

```javascript
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:

```javascript
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](https://github.com/ElemeFE/element/blob/dev/examples/docs/en-US/quickstart.md#L69-L75)*

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:

```javascript
// 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`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/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`](https://github.com/ElemeFE/element/blob/main/src/utils/popup/popup-manager.js) falls back to this value when no global configuration is present.