Dialog

Dialog component enhanced based on Element Plus Dialog.

Informs users while preserving the current page state.

Basic usage

Dialog pops up a dialog box, and it's quite customizable.

Set model-value / v-model attribute with a Boolean, and Dialog shows when it is true. The Dialog has two parts: body and footer, and the latter requires a slot named footer. The optional title attribute (empty by default) is for defining a title. Finally, this example demonstrates how before-close is used.

<template>
  <bk-button plain @click="dialogVisible = true"> Click to open the Dialog </bk-button>

  <bk-dialog
    v-model="dialogVisible"
    title="Tips"
    width="500"
    :before-close="handleClose"
    class="el-dialog-fade"
  >
    <span>This is a message</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"
import { ElMessageBox } from "vue-business-kit"

const dialogVisible = ref(false)

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

Hide Source

TIP

before-close only works when user clicks the close icon or the backdrop. If you have buttons that close the Dialog in the footer named slot, you can add what you would do with before-close in the buttons' click event handler.

Customized Content

The content of Dialog can be anything, even a table or a form. This example shows how to use Table and Form with Dialog.

<template>
  <div class="flex flex-wrap gap-1">
    <bk-button class="!ml-0" plain @click="dialogTableVisible = true">
      Open a Table nested Dialog
    </bk-button>

    <bk-button class="!ml-0" plain @click="dialogFormVisible = true">
      Open a Form nested Dialog
    </bk-button>
  </div>

  <bk-dialog v-model="dialogTableVisible" title="Shipping address" width="800">
    <bk-table :raw-data="gridData">
      <bk-table-column property="date" label="Date" width="150" />
      <bk-table-column property="name" label="Name" width="200" />
      <bk-table-column property="address" label="Address" />
    </bk-table>
  </bk-dialog>

  <bk-dialog v-model="dialogFormVisible" title="Shipping address" width="500">
    <bk-form :model="form">
      <bk-form-item label="Promotion name" :label-width="formLabelWidth">
        <el-input v-model="form.name" autocomplete="off" />
      </bk-form-item>
      <bk-form-item label="Zones" :label-width="formLabelWidth">
        <el-select v-model="form.region" placeholder="Please select a zone">
          <el-option label="Zone No.1" value="shanghai" />
          <el-option label="Zone No.2" value="beijing" />
        </el-select>
      </bk-form-item>
    </bk-form>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogFormVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogFormVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { reactive, ref } from "vue"

const dialogTableVisible = ref(false)
const dialogFormVisible = ref(false)
const formLabelWidth = "140px"

const form = reactive({
  name: "",
  region: "",
  date1: "",
  date2: "",
  delivery: false,
  type: [],
  resource: "",
  desc: ""
})

const gridData = [
  {
    date: "2016-05-02",
    name: "John Smith",
    address: "No.1518,  Jinshajiang Road, Putuo District"
  },
  {
    date: "2016-05-04",
    name: "John Smith",
    address: "No.1518,  Jinshajiang Road, Putuo District"
  },
  {
    date: "2016-05-01",
    name: "John Smith",
    address: "No.1518,  Jinshajiang Road, Putuo District"
  },
  {
    date: "2016-05-03",
    name: "John Smith",
    address: "No.1518,  Jinshajiang Road, Putuo District"
  }
]
</script>

Hide Source

Customized Header

The header slot can be used to customize the area where the title is displayed. In order to maintain accessibility, use the title attribute in addition to using this slot, or use the titleId slot property to specify which element should be read out as the dialog title.

<template>
  <bk-button plain @click="visible = true"> Open Dialog with customized header </bk-button>

  <bk-dialog v-model="visible" :show-close="false" width="500">
    <template #header="{ close, titleId, titleClass }">
      <div class="my-header">
        <h4 :id="titleId" :class="titleClass">This is a custom header!</h4>
        <bk-button type="danger" @click="close">
          <bk-icon class="el-icon--left" icon="tabler:circle-x-filled"></bk-icon>
          Close
        </bk-button>
      </div>
    </template>
    This is dialog content.
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const visible = ref(false)
</script>

<style scoped>
.my-header {
  display: flex;
  flex-direction: row;
  justify-content: space-between;
  gap: 16px;
}
</style>

Hide Source

Nested Dialog

If a Dialog is nested in another Dialog, append-to-body is required.

Normally we do not recommend using nested Dialog. If you need multiple Dialogs rendered on the page, you can simply flat them so that they're siblings to each other. If you must nest a Dialog inside another Dialog, set append-to-body of the nested Dialog to true, and it will append to body instead of its parent node, so both Dialogs can be correctly rendered.

<template>
  <bk-button plain @click="outerVisible = true"> Open the outer Dialog </bk-button>

  <bk-dialog v-model="outerVisible" title="Outer Dialog" width="800">
    <span>This is the outer Dialog</span>
    <bk-dialog v-model="innerVisible" width="500" title="Inner Dialog" append-to-body>
      <span>This is the inner Dialog</span>
    </bk-dialog>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="outerVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="innerVisible = true"> Open the inner Dialog </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const outerVisible = ref(false)
const innerVisible = ref(false)
</script>

Hide Source

Centered content

Dialog's content can be centered.

Setting center to true will center dialog's header and footer horizontally. center only affects Dialog's header and footer. The body of Dialog can be anything, so sometimes it may not look good when centered. You need to write some CSS if you wish to center the body as well.

<template>
  <bk-button plain @click="centerDialogVisible = true"> Click to open the Dialog </bk-button>

  <bk-dialog v-model="centerDialogVisible" title="Warning" width="500" center>
    <span> It should be noted that the content will not be aligned in center by default </span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="centerDialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="centerDialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const centerDialogVisible = ref(false)
</script>

Hide Source

TIP

The content of Dialog is lazily rendered, which means the default slot is not rendered onto the DOM until it is firstly opened. Therefore, if you need to perform a DOM manipulation or access a component using ref, do it in the open event callback.

Align Center dialog

Open dialog from the center of the screen.

Setting align-center to true will center the dialog both horizontally and vertically. The prop top will not work at the same time because the dialog is vertically centered in a flexbox.

<template>
  <bk-button plain @click="centerDialogVisible = true"> Click to open the Dialog </bk-button>

  <bk-dialog v-model="centerDialogVisible" title="Warning" width="500" align-center>
    <span>Open the dialog from the center from the screen</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="centerDialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="centerDialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const centerDialogVisible = ref(false)
</script>

Hide Source

Destroy on Close

When this is feature is enabled, the content under default slot will be destroyed with a v-if directive. Enable this when you have perf concerns.

Note that by enabling this feature, the content will not be rendered before transition.beforeEnter dispatched, there will only be overlay header(if any) footer(if any).

<template>
  <bk-button plain @click="centerDialogVisible = true"> Click to open Dialog </bk-button>

  <bk-dialog v-model="centerDialogVisible" title="Notice" width="500" destroy-on-close center>
    <span>
      Notice: before the dialog is opened for the first time, this node and the one below will not
      be rendered.
    </span>
    <div>
      <strong>Extra content (Not rendered)</strong>
    </div>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="centerDialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="centerDialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const centerDialogVisible = ref(false)
</script>

Hide Source

Draggable Dialog

Try to drag the header part.

Set draggable to true to drag. Set overflow to true can drag overflow the viewport.

<template>
  <div class="flex flex-wrap gap-1">
    <bk-button class="!ml-0" plain @click="dialogVisible = true">
      Open a draggable Dialog
    </bk-button>
    <bk-button class="!ml-0" plain @click="dialogOverflowVisible = true">
      Open a overflow draggable Dialog
    </bk-button>
    <bk-button class="!ml-0" plain @click="customDraggingVisible = true">
      Open a custom dragging style Dialog
    </bk-button>
  </div>

  <bk-dialog v-model="dialogVisible" title="Tips" width="500" draggable>
    <span>It's a draggable Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>

  <bk-dialog v-model="dialogOverflowVisible" title="Tips" width="500" draggable overflow>
    <span>It's a overflow draggable Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogOverflowVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogOverflowVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>

  <bk-dialog
    v-model="customDraggingVisible"
    class="custom-dragging-style"
    title="Custom Dragging Style"
    width="500"
    draggable
  >
    <span>This dialog has custom dragging styles. Try dragging it to see the effects!</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="customDraggingVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="customDraggingVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const dialogVisible = ref(false)
const dialogOverflowVisible = ref(false)
const customDraggingVisible = ref(false)
</script>

<style scoped>
:global(.custom-dragging-style.is-dragging) {
  border: 2px dashed var(--el-color-primary);
  opacity: 0.65;
}
</style>

Hide Source

TIP

When using modal = false, please make sure that append-to-body was set to true, because Dialog was positioned by position: relative, when modal gets removed, Dialog will position itself based on the current position in the DOM, instead of Document.Body, thus the style will be messed up.

Fullscreen

Set the fullscreen attribute to open fullscreen dialog.

<template>
  <bk-button plain @click="dialogVisible = true"> Open the fullscreen Dialog </bk-button>

  <bk-dialog v-model="dialogVisible" fullscreen>
    <span>It's a fullscreen Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const dialogVisible = ref(false)
</script>

Hide Source

TIP

If fullscreen is true, width top draggable attributes don't work.

Modal

Setting modal to false will hide modal (overlay) of dialog.

modal-penetrable attribute is added, which can be penetrable.

<template>
  <bk-button plain @click="dialogVisible = true"> Open the modal Dialog </bk-button>

  <bk-dialog v-model="dialogVisible" :modal="false" modal-penetrable>
    <span>It's a modal Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const dialogVisible = ref(false)
</script>

Hide Source

Custom Animation

Customize dialog animation through the transition attribute, which accepts either:

• ​Transition name​​ (string)

• ​​Vue transition configuration​​ (object)

Examples include scale, slide, fade, bounce animations and object-based configurations with custom event handlers.

<template>
  <div>
    <bk-button plain @click="openDialog('fade')"> Default </bk-button>
    <bk-button plain @click="openDialog('scale')"> Scale </bk-button>
    <bk-button plain @click="openDialog('slide')"> Slide </bk-button>
    <bk-button plain @click="openDialog('bounce')"> Bounce </bk-button>
    <bk-button plain @click="openDialogWithObject"> Object Config </bk-button>
  </div>

  <bk-dialog
    v-model="dialogVisible"
    class="custom-transition-dialog"
    :title="`${currentAnimation} Animation Dialog`"
    width="30%"
    :transition="transitionConfig"
  >
    <div>
      <p>
        Current animation: <strong>{{ currentAnimation }}</strong>
      </p>
      <p>This dialog demonstrates the {{ currentAnimation }} animation effect.</p>
      <p v-if="isObjectConfig">
        <strong>Using object configuration:</strong><br />
        <code>{{ JSON.stringify(transitionConfig, null, 2) }}</code>
      </p>
    </div>
    <template #footer>
      <bk-button @click="dialogVisible = false">Cancel</bk-button>
      <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { computed, ref } from "vue"
import type { DialogTransition } from "vue-business-kit"

const dialogVisible = ref(false)
const currentAnimation = ref("fade")
const isObjectConfig = ref(false)

const transitionConfig = computed<DialogTransition>(() => {
  if (isObjectConfig.value) {
    return {
      name: "dialog-custom-object",
      appear: true,
      mode: "out-in",
      duration: 500
    }
  }
  return `dialog-${currentAnimation.value}`
})

const openDialog = (type: string) => {
  currentAnimation.value = type
  isObjectConfig.value = false
  dialogVisible.value = true
}

const openDialogWithObject = () => {
  currentAnimation.value = "object-config"
  isObjectConfig.value = true
  dialogVisible.value = true
}
</script>

<style scoped>
code {
  background: var(--el-bg-color-page);
  padding: 4px 8px;
  border-radius: 4px;
  font-size: 12px;
  display: block;
  margin-top: 8px;
}
</style>

<style>
/* Scale Animation */
.dialog-scale-enter-active,
.dialog-scale-leave-active,
.dialog-scale-enter-active .el-dialog,
.dialog-scale-leave-active .el-dialog {
  transition: all 0.2s cubic-bezier(0.645, 0.045, 0.355, 1);
}

.dialog-scale-enter-from,
.dialog-scale-leave-to {
  opacity: 0;
}

.dialog-scale-enter-from .el-dialog,
.dialog-scale-leave-to .el-dialog {
  transform: scale(0.5);
  opacity: 0;
}

/* Slide Animation */
.dialog-slide-enter-active,
.dialog-slide-leave-active,
.dialog-slide-enter-active .el-dialog,
.dialog-slide-leave-active .el-dialog {
  transition: all 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
}

.dialog-slide-enter-from,
.dialog-slide-leave-to {
  opacity: 0;
}

.dialog-slide-enter-from .el-dialog,
.dialog-slide-leave-to .el-dialog {
  transform: translateY(-100px);
  opacity: 0;
}

/* Bounce Animation */
.dialog-bounce-enter-active,
.dialog-bounce-leave-active,
.dialog-bounce-enter-active .el-dialog,
.dialog-bounce-leave-active .el-dialog {
  transition: all 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275);
}

.dialog-bounce-enter-from,
.dialog-bounce-leave-to {
  opacity: 0;
}

.dialog-bounce-enter-from .el-dialog,
.dialog-bounce-leave-to .el-dialog {
  transform: scale(0.3) translateY(-50px);
  opacity: 0;
}

/* Object Configuration Animation */
.dialog-custom-object-enter-active,
.dialog-custom-object-leave-active,
.dialog-custom-object-enter-active .el-dialog,
.dialog-custom-object-leave-active .el-dialog {
  transition: all 0.5s cubic-bezier(0.25, 0.8, 0.25, 1);
}

.dialog-custom-object-enter-from,
.dialog-custom-object-leave-to {
  opacity: 0;
}

.dialog-custom-object-enter-from .el-dialog,
.dialog-custom-object-leave-to .el-dialog {
  transform: rotate(180deg) scale(0.5);
  opacity: 0;
}
</style>

Hide Source

TIP

Animation classes are dynamically generated based on the transition name. For granular control over animation behavior, you may explicitly define these classes. Refer to custom-transition-classes for details.

Events

Open developer console (ctrl + shift + J), to see order of events.

<template>
  <bk-button plain @click="dialogVisible = true"> Open the event Dialog </bk-button>

  <bk-dialog
    v-model="dialogVisible"
    modal-class="overide-animation"
    :before-close="
      (doneFn) => {
        console.log('before-close'), doneFn()
      }
    "
    @open="console.log('open')"
    @open-auto-focus="console.log('open-auto-focus')"
    @opened="console.log('opened')"
    @close="console.log('close')"
    @close-auto-focus="console.log('close-auto-focus')"
    @closed="console.log('closed')"
  >
    <span>It's a event Dialog</span>
    <template #footer>
      <div class="dialog-footer">
        <bk-button @click="dialogVisible = false">Cancel</bk-button>
        <bk-button type="primary" @click="dialogVisible = false"> Confirm </bk-button>
      </div>
    </template>
  </bk-dialog>
</template>

<script lang="ts" setup>
import { ref } from "vue"

const dialogVisible = ref(false)
</script>

Hide Source

Dialog API

Dialog Attributes

Element Plus Dialog Attributes

Name	Description	Type	Default
model-value / v-model	visibility of Dialog	boolean	false
title	title of Dialog. Can also be passed with a named slot (see the following table)	string	''
width	width of Dialog, default is 50%	string / number	''
fullscreen	whether the Dialog takes up full screen	boolean	false
top	value for margin-top of Dialog CSS, default is 15vh	string	''
modal	whether a mask is displayed	boolean	true
modal-penetrable	whether the mask is penetrable. The modal attribute must be false.	boolean	false
modal-class	custom class names for mask	string	—
header-class	custom class names for header wrapper	string	—
body-class	custom class names for body wrapper	string	—
footer-class	custom class names for footer wrapper	string	—
append-to-body	whether to append Dialog itself to body. A nested Dialog should have this attribute set to true	boolean	false
append-to	which element the Dialog appends to. Will override append-to-body	CSSSelector / HTMLElement	body
lock-scroll	whether scroll of body is disabled while Dialog is displayed	boolean	true
open-delay	the Time(milliseconds) before open	number	0
close-delay	the Time(milliseconds) before close	number	0
close-on-click-modal	whether the Dialog can be closed by clicking the mask	boolean	true
close-on-press-escape	whether the Dialog can be closed by pressing ESC	boolean	true
show-close	whether to show a close button	boolean	true
before-close	callback before Dialog closes, and it will prevent Dialog from closing, use done to close the dialog	Function	—
draggable	enable dragging feature for Dialog	boolean	false
overflow	draggable Dialog can overflow the viewport	boolean	false
center	whether to align the header and footer in center	boolean	false
align-center	whether to align the dialog both horizontally and vertically	boolean	false
destroy-on-close	destroy elements in Dialog when closed	boolean	false
close-icon	custom close icon, default is Close	string / Component	—
z-index	same as z-index in native CSS, z-order of dialog	number	—
header-aria-level	header's aria-level attribute	string	2
transition	custom transition configuration for dialog animation. Can be a string (transition name) or an object with Vue transition props	string / object	dialog-fade

Dialog Slots

Element Plus Dialog Slots

Name	Description
default	default content of Dialog
header	content of the Dialog header; Replacing this removes the title, but does not remove the close button.
footer	content of the Dialog footer

Dialog Events

Element Plus Dialog Events

Name	Description	Type
open	triggers when the Dialog opens	Function
opened	triggers when the Dialog opening animation ends	Function
close	triggers when the Dialog closes	Function
closed	triggers when the Dialog closing animation ends	Function
open-auto-focus	triggers after Dialog opens and content focused	Function
close-auto-focus	triggers after Dialog closed and content focused	Function

Dialog Exposes

Element Plus Dialog Events

Name	Description	Type
resetPosition	reset position	Function
handleClose	close dialog	Function

FAQ

Using dialog in SFC, the scope style does not take effect

Typical issue: #10515

PS: Since the dialog is rendered using Teleport, the style of the root node is recommended to be written globally.

When the dialog is displayed and hidden, there is a situation where the page elements are displaced back and forth

Typical issue: #10481

PS: It is recommended to place the scroll area inside a vue mounted node, e.g. <div id="app" />, and use the overflow: hidden style for the body.