El Dialog

Element Plus Dialog Component

Informs users while preserving the current page state.

When to Invoke

Invoke this skill when:

• User needs to display modal content
• User wants to create confirmation dialogs
• User needs form dialogs
• User wants draggable dialogs
• User needs nested dialogs
• User asks about dialog customization

Features

• Modal/Modeless: With or without overlay
• Customizable Size: Width, height, fullscreen
• Draggable: Drag dialog by header
• Nested Support: Multiple dialog layers
• Custom Content: Header, body, footer slots
• Animations: Custom transition effects
• Center Alignment: Horizontal and vertical centering
• Destroy on Close: Clean up DOM when closed

API Reference

Dialog Attributes

| Name | Description | Type | Default | |------|-------------|------|---------| | model-value / v-model | visibility of Dialog | boolean | false | | title | title of Dialog | string | '' | | width | width of Dialog | string \| number | '' | | fullscreen | whether fullscreen | boolean | false | | top | value for margin-top | string | '' | | modal | whether a mask is displayed | boolean | true | | modal-penetrable | whether the mask is penetrable | boolean | false | | modal-class | custom class names for mask | string | — | | header-class | custom class names for header | string | — | | body-class | custom class names for body | string | — | | footer-class | custom class names for footer | string | — | | append-to-body | whether to append Dialog to body | boolean | false | | append-to | which element the Dialog appends to | CSSSelector \| HTMLElement | body | | lock-scroll | whether scroll of body is disabled | boolean | true | | open-delay | time before open (ms) | number | 0 | | close-delay | time before close (ms) | number | 0 | | close-on-click-modal | whether can be closed by clicking mask | boolean | true | | close-on-press-escape | whether can be closed by ESC | boolean | true | | show-close | whether to show close button | boolean | true | | before-close | callback before close | (done: DoneFn) => void | — | | draggable | enable dragging | boolean | false | | overflow | draggable can overflow viewport | boolean | false | | center | align header and footer in center | boolean | false | | align-center | align dialog horizontally and vertically | boolean | false | | destroy-on-close | destroy elements when closed | boolean | false | | close-icon | custom close icon | string \| Component | — | | z-index | z-order of dialog | number | — | | header-aria-level | header's aria-level attribute | string | 2 | | transition | custom transition configuration | string \| object | dialog-fade |

Dialog Slots

| Name | Description | |------|-------------| | default | default content of Dialog | | header | content of the Dialog header | | footer | content of the Dialog footer |

Dialog Events

| Name | Description | Type | |------|-------------|------| | open | triggers when Dialog opens | () => void | | opened | triggers when opening animation ends | () => void | | close | triggers when Dialog closes | () => void | | closed | triggers when closing animation ends | () => void | | open-auto-focus | triggers after Dialog opens and content focused | () => void | | close-auto-focus | triggers after Dialog closed and content focused | () => void |

Dialog Exposes

| Name | Description | Type | |------|-------------|------| | resetPosition | reset position | () => void | | handleClose | close dialog | () => void |

Usage Examples

Basic Dialog

  Open Dialog

  
    This is a message
    
      
        Cancel
        Confirm
      
    
  

import { ref } from 'vue'

const dialogVisible = ref(false)

Custom Content

  Open Form Dialog

  
    
      
        
      
      
        
          
          
        
      
    
    
      Cancel
      Confirm
    
  

import { ref, reactive } from 'vue'

const dialogVisible = ref(false)
const formLabelWidth = '140px'

const form = reactive({
  name: '',
  region: ''
})

Custom Header

  
    
      
        Custom Header
        
          
          Close
        
      
    
    This is content
  

Nested Dialog

  Open Outer Dialog

  
    Open Inner Dialog
    
    
  

import { ref } from 'vue'

const outerVisible = ref(false)
const innerVisible = ref(false)

Centered Content

  
    Content should be centered
    
      Cancel
      Confirm
    
  

Align Center

  
    Dialog is centered both horizontally and vertically
  

Draggable Dialog

  
    Drag the header to move the dialog
  

Fullscreen

  
    Fullscreen dialog
  

Before Close

  
    This dialog will ask for confirmation before closing
  

import { ref } from 'vue'
import { ElMessageBox } from 'element-plus'

const dialogVisible = ref(false)

const handleClose = (done) => {
  ElMessageBox.confirm('Are you sure to close this dialog?')
    .then(() => {
      done()
    })
    .catch(() => {
      // catch error
    })
}

Destroy on Close

  
    Content will be destroyed when closed
  

Modal Configuration

  
  
    Dialog without modal overlay
  

Custom Animation

  
    Dialog with custom animation
  

Common Issues

1. Scoped Styles Not Working

Dialog uses Teleport, so styles should be global:

/* Global styles for dialog */
.my-dialog .el-dialog__body {
  padding: 20px;
}

2. Page Scroll Issues

Use lock-scroll properly:

3. Nested Dialog Positioning

Use append-to-body for nested dialogs:

Component Interactions

With Form

  
    
      
        
      
    
    
      Cancel
      Save
    
  

const handleSubmit = async () => {
  try {
    await formRef.value.validate()
    await saveUser(form)
    dialogVisible.value = false
  } catch (error) {
    console.error('Validation failed')
  }
}

With Table

Best Practices

1. Use v-model: Always use v-model for visibility control
2. Set width: Set appropriate width for content
3. Use before-close: Handle unsaved changes gracefully
4. Destroy on close: Use destroy-on-close for performance
5. Nested dialogs: Always use append-to-body for nested dialogs
6. Accessibility: Use proper title and aria-level

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jiaiyan
• Source: jiaiyan/element-plus-skills
• License: MIT
• Homepage: https://skills.sh/jiaiyan/element-plus-skills/element-plus-skills

Install and usage instructions live in the source repository linked above.