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>
  <b-button small @click.prevent="dialogVisible = true">Open Dialog</b-button>

  <b-dialog
    v-model="dialogVisible"
    title="Tips"
    width="30%"
    :before-close="handleClose"
  >
    <span>This is a message</span>
    <template #footer>
      <div class="flex justify-end">
        <b-button class="mr-4" @click="dialogVisible = false">Cancel</b-button>
        <b-button type="primary" @click="dialogVisible = false"
          >Confirm</b-button
        >
      </div>
    </template>
  </b-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { BMessageBox } from 'bigin-ui'

const dialogVisible = ref(false)

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

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.

Dialog Size

Predefined 5 sizes from 400px (xsmall) to 1040px (xlarge), each size +/- 160px. Or set custom value by width.

---

<template>
  <b-space wrap>
    <b-button small @click="openDialog('xsmall')">xsmall</b-button>
    <b-button small @click="openDialog('small')">small</b-button>
    <b-button small @click="openDialog('default')">default</b-button>
    <b-button small @click="openDialog('large')">large</b-button>
    <b-button small @click="openDialog('xlarge')">xlarge</b-button>
    <b-button small @click="dialogCustomVisible = true">custom</b-button>
    <b-button small @click="dialogFullscreenVisible = true"
      >fullscreen</b-button
    >
  </b-space>

  <b-dialog
    v-model="dialogVisible"
    :size="dialogSize"
    :title="`Dialog ${dialogSize}`"
    :scrollable="true"
    :scrollable-max-height="40"
  >
    <p>
      Lorem ipsum dolor sit amet consectetur adipisicing elit. Excepturi sint,
      eum sapiente unde obcaecati quas consectetur consequuntur velit laboriosam
      cumque atque eos natus, quisquam ipsam tempora dicta modi aliquam iure.
    </p>
    <template #footer>
      <div class="flex justify-end">
        <b-button @click="dialogVisible = false">Close</b-button>
      </div>
    </template>
  </b-dialog>

  <b-dialog v-model="dialogCustomVisible" width="30%" title="Dialog width 30%">
    <p>
      Lorem ipsum dolor sit amet consectetur adipisicing elit. Excepturi sint,
      eum sapiente unde obcaecati quas consectetur consequuntur velit laboriosam
      cumque atque eos natus, quisquam ipsam tempora dicta modi aliquam iure.
    </p>
    <template #footer>
      <div class="flex justify-end">
        <b-button @click="dialogCustomVisible = false">Close</b-button>
      </div>
    </template>
  </b-dialog>

  <b-dialog
    v-model="dialogFullscreenVisible"
    fullscreen
    title="Dialog fullscreen"
  >
    <p>
      Lorem ipsum dolor sit amet consectetur adipisicing elit. Excepturi sint,
      eum sapiente unde obcaecati quas consectetur consequuntur velit laboriosam
      cumque atque eos natus, quisquam ipsam tempora dicta modi aliquam iure.
    </p>
    <template #footer>
      <div class="flex justify-end">
        <b-button @click="dialogFullscreenVisible = false">Close</b-button>
      </div>
    </template>
  </b-dialog>
</template>

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

const dialogVisible = ref(false)
const dialogCustomVisible = ref(false)
const dialogFullscreenVisible = ref(false)
const dialogSize = ref('default')

const openDialog = (size: string) => {
  dialogSize.value = size
  dialogVisible.value = true
}
</script>

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>
  <b-button small @click="visible = true">
    Open Dialog with customized header
  </b-button>
  <b-dialog v-model="visible" :show-close="false">
    <template #header="{ close, titleId, titleClass }">
      <div class="flex w-full items-center justify-between">
        <h4 :id="titleId" :class="titleClass">This is a custom header!</h4>
        <b-button danger small :prefix-icon="Close" @click="close">
          Close
        </b-button>
      </div>
    </template>
    This is dialog content.
  </b-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Close } from '@bigin/icons-vue'

const visible = ref(false)
</script>

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>
  <b-button small @click="outerVisible = true">open the outer Dialog</b-button>

  <b-dialog v-model="outerVisible" title="Outer Dialog">
    <template #default>
      <b-dialog
        v-model="innerVisible"
        width="30%"
        title="Inner Dialog"
        append-to-body
      />
    </template>
    <template #footer>
      <div class="dialog-footer">
        <b-button @click="outerVisible = false">Cancel</b-button>
        <b-button type="primary" @click="innerVisible = true"
          >open the inner Dialog</b-button
        >
      </div>
    </template>
  </b-dialog>
</template>

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

const outerVisible = ref(false)
const innerVisible = ref(false)
</script>
<style scoped>
.dialog-footer button:first-child {
  margin-right: 10px;
}
</style>

Centered

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>
  <b-button small @click="centerDialogVisible = true">Open Dialog</b-button>

  <b-dialog v-model="centerDialogVisible" title="Warning" size="small" center>
    <span
      >It should be noted that the content will not be aligned in center by
      default</span
    >
    <template #footer>
      <span class="flex justify-end">
        <b-button class="mr-4" @click="centerDialogVisible = false"
          >Cancel</b-button
        >
        <b-button type="primary" @click="centerDialogVisible = false"
          >Confirm</b-button
        >
      </span>
    </template>
  </b-dialog>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const centerDialogVisible = ref(false)
</script>

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>
  <b-button small @click="centerDialogVisible = true">Open Dialog</b-button>

  <b-dialog
    v-model="centerDialogVisible"
    title="Notice"
    width="30%"
    destroy-on-close
    center
  >
    <span
      >Notice: before dialog gets opened for the first time this node and the
      one bellow will not be rendered</span
    >
    <div>
      <strong>Extra content (Not rendered)</strong>
    </div>
    <template #footer>
      <span class="flex justify-end">
        <b-button class="mr-4" @click="centerDialogVisible = false"
          >Cancel</b-button
        >
        <b-button type="primary" @click="centerDialogVisible = false"
          >Confirm</b-button
        >
      </span>
    </template>
  </b-dialog>
</template>

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

const centerDialogVisible = ref(false)
</script>

Draggable Dialog

Try to drag the header part. Set draggable to true to drag.

---

<template>
  <b-button small @click="dialogVisible = true">Open Dialog </b-button>

  <b-dialog v-model="dialogVisible" title="Tips" size="small" draggable>
    <span>It's a draggable Dialog</span>
    <template #footer>
      <span class="flex justify-end">
        <b-button class="mr-4" @click="dialogVisible = false">Cancel</b-button>
        <b-button type="primary" @click="dialogVisible = false"
          >Confirm</b-button
        >
      </span>
    </template>
  </b-dialog>
</template>

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

const dialogVisible = ref(false)
</script>

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.

Attributes

Attribute	Description	Type	Accepted Values	Default
model-value / v-model	visibility of Dialog	boolean	—	—
title	title of Dialog. Can also be passed with a named slot (see the following table)	string	—	—
size	size of Dialog	sizeProps	—	default
xsmall	size of Dialog	boolean	—	false
small	size of Dialog	boolean	—	false
large	size of Dialog	boolean	—	false
xlarge	size of Dialog	boolean	—	false
width	width of Dialog	string / number	—	—
fullscreen	whether the Dialog takes up full screen	boolean	—	false
top	value for margin-top of Dialog CSS	string	—	15vh
modal	whether a mask is displayed	boolean	—	true
append-to-body	whether to append Dialog itself to body. A nested Dialog should have this attribute set to true	boolean	—	false
lock-scroll	whether scroll of body is disabled while Dialog is displayed	boolean	—	true
modal-class	custom class names for Dialog's overlay	string	—	—
container-class	custom class names for Dialog's container	string	—	—
header-class	custom class names for Dialog's header	string	—	—
body-class	custom class names for Dialog's body	string	—	—
footer-class	custom class names for Dialog's footer	string	—	—
open-delay	Time(milliseconds) before open	number	—	0
close-delay	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	function(done)，done is used to close the Dialog	—	—
draggable	enable dragging feature for Dialog	boolean	—	false
center	whether to align the header and footer in center	boolean	—	false
scrollable	enable scrollable body	boolean	—	false
scrollable-height	scrollable height	string / number	—	—
scrollable-max-height	scrollable max height	string / number	—	—
destroy-on-close	Destroy elements in Dialog when closed	boolean	—	false

Slots

Name	Description
—	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

Events

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