Dialog

Represents a part of an application that a user interacts with to perform a task.

Usage

Dialog uses the native dialog element.

import { registerDialog } from '@vonage/vivid-api';

registerDialog('your-prefix');

Use the modal attribute to set the dialog as Modal

Modal dialogs prevent users from interacting with the rest of the application until the dialog is closed and render a backdrop behind the dialog.
Non-modal dialogs allow users to interact with the rest of the application while the dialog is open.

<script setup lang="ts">
import { ref, useTemplateRef } from 'vue';
import { VButton, VCheckbox, VDialog, VIcon, VRadio, VRadioGroup } from '@vonage/vivid-api-vue';
const modal = ref('false');
const dialog = useTemplateRef<InstanceType<typeof VDialog>>('dialog');

function openDialog() {
  if (dialog.value?.element) {
    dialog.value.element.open = true;
  }
}

function closeDialog() {
  if (dialog.value?.element) {
    dialog.value.element.open = false;
  }
}
</script>

<template>
  <div class="buttons-wrapper">
    <VRadioGroup v-model="modal">
      <VRadio label="Non-modal" value="false" />
      <VRadio label="Modal" value="true" />
    </VRadioGroup>
    <VButton appearance="filled" label="Open Dialog" @click="openDialog" />
  </div>

  <VDialog ref="dialog" :modal="modal === 'true'" headline="Headline" subtitle="subtitle">
    <template #icon><VIcon name="info-line" label="Info" /></template>
    <VCheckbox slot="footer" label="Checkbox" />
    <VButton slot="action-items" label="Cancel" appearance="outlined" @click="closeDialog" /><VButton slot="action-items" label="Ok" appearance="filled" @click="closeDialog" />
  </VDialog>
</template>

<style>
.buttons-wrapper {
  display: flex;
  align-items: center;
  gap: 16px;
}
</style>

<div class="buttons-wrapper">
  <vwc-radio-group>
    <vwc-radio label="Non-modal" value="false" checked></vwc-radio>
    <vwc-radio label="Modal" value="true"></vwc-radio>
  </vwc-radio-group>
  <vwc-button appearance="filled" label="Open Dialog" onclick="openDialog()"></vwc-button>
</div>

<vwc-dialog id="vwc-dialog" headline="Headline" subtitle="subtitle">
  <vwc-icon slot="icon" name="info-line" label="Info"></vwc-icon>
  <vwc-checkbox slot="footer" label="Checkbox"></vwc-checkbox>
  <vwc-button slot="action-items" label="Cancel" appearance="outlined" onclick="closeDialog()"></vwc-button>
  <vwc-button slot="action-items" label="Ok" appearance="filled" onclick="closeDialog()"></vwc-button>
</vwc-dialog>

<script>
  const dialog = document.querySelector('#vwc-dialog');

  function openDialog() {
    dialog.open = true;
  }

  document.querySelector('vwc-radio-group').addEventListener('change', (e) => {
    dialog.modal = e.currentTarget.value === 'true';
  });

  function closeDialog() {
    dialog.open = false;
  }
</script>

<style>
  .buttons-wrapper {
    display: flex;
    align-items: center;
    gap: 16px;
  }
</style>

Open

Sets or returns whether a dialog should be open or not.

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { VButton, VDialog } from '@vonage/vivid-api-vue';
const dialog = useTemplateRef<InstanceType<typeof VDialog>>('dialog');

function toggleDialog() {
  if (dialog.value?.element) {
    dialog.value.element.open = !dialog.value.element.open;
  }
}
</script>

<template>
  <VButton label="Toggle Dialog Open" @click="toggleDialog" appearance="outlined" />
  <VDialog ref="dialog" headline="I'm a Dialog" subtitle="subtitle" />
</template>

Dismiss

When using this attribute, ensure that the dialog can be closed by other means.

No-light-dismiss

Use the no-light-dismiss attribute to prevent a modal dialog from being dismissed by clicking outside it.

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { VButton, VDialog } from '@vonage/vivid-api-vue';
const dialog = useTemplateRef<InstanceType<typeof VDialog>>('dialog');
function openDialog() {
  if (dialog.value?.element) {
    dialog.value.element.open = true;
  }
}
</script>

<template>
  <VButton label="Open modal dialog" @click="openDialog" appearance="outlined" />
  <VDialog ref="dialog" no-light-dismiss headline="Headline" modal />
</template>

<vwc-button label="Open modal dialog" onclick="document.querySelector('vwc-dialog').open = true" appearance="outlined"></vwc-button> <vwc-dialog no-light-dismiss headline="Headline" modal></vwc-dialog>

No-Dismiss-On-Esc

Use the no-dismiss-on-esc attribute to prevent a modal dialog from being dismissed by pressing ESC.

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { VButton, VDialog } from '@vonage/vivid-api-vue';
const dialog = useTemplateRef<InstanceType<typeof VDialog>>('dialog');
function openDialog() {
  if (dialog.value?.element) {
    dialog.value.element.open = true;
  }
}
</script>

<template>
  <VButton label="Open modal dialog" @click="openDialog" appearance="outlined" />
  <VDialog ref="dialog" no-dismiss-on-esc headline="Headline" modal />
</template>

<vwc-button label="Open modal dialog" onclick="document.querySelector('vwc-dialog').open = true" appearance="outlined"></vwc-button> <vwc-dialog no-dismiss-on-esc headline="Headline" modal></vwc-dialog>

No-Dismiss-Button

Use the no-dismiss-button attribute to remove the dismiss button from the dialog.

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { VButton, VDialog } from '@vonage/vivid-api-vue';
const dialog = useTemplateRef<InstanceType<typeof VDialog>>('dialog');
function openDialog() {
  if (dialog.value?.element) {
    dialog.value.element.open = true;
  }
}
</script>

<template>
  <VButton label="Open modal dialog" @click="openDialog" appearance="outlined" />
  <VDialog ref="dialog" no-dismiss-button headline="Headline" modal />
</template>

<vwc-button label="Open modal dialog" onclick="document.querySelector('vwc-dialog').open = true" appearance="outlined"></vwc-button> <vwc-dialog no-dismiss-button headline="Headline" modal></vwc-dialog>

Non-Dismissible

The non-dismissible attribute combines no-light-dismiss, no-dismiss-on-esc, and no-dismiss-button.

<script setup lang="ts">
import { useTemplateRef } from 'vue';
import { VButton, VDialog } from '@vonage/vivid-api-vue';
const dialog = useTemplateRef<InstanceType<typeof VDialog>>('dialog');
function openDialog() {
  if (dialog.value?.element) {
    dialog.value.element.open = true;
  }
}
</script>

<template>
  <VButton label="Open modal dialog" @click="openDialog" appearance="outlined" />
  <VDialog ref="dialog" non-dismissible headline="Headline" modal />
</template>

<vwc-button label="Open modal dialog" onclick="document.querySelector('vwc-dialog').open = true" appearance="outlined"></vwc-button> <vwc-dialog non-dismissible headline="Headline" modal></vwc-dialog>

Dismiss-Button-Aria-Label

The dismiss button is automatically given a localized version of the word “close”.
This can be overridden using dismiss-button-aria-label.

Return Value

Use returnValue to get or set the return value.
Often used to indicate which button the user pressed to close it.

<script setup lang="ts">
import { ref, useTemplateRef } from 'vue';
import { VButton, VDialog } from '@vonage/vivid-api-vue';
const returnValue = ref('');
const dialog = useTemplateRef<InstanceType<typeof VDialog>>('dialog');

function openDialog() {
if (dialog.value?.element) {
dialog.value.element.open = true;
}
}

function handleClick(e: any) {
const buttonType = e.currentTarget.label;
console.log(buttonType);
if (dialog.value?.element) {
dialog.value.element.returnValue = buttonType;
dialog.value.element.open = false;
}
}

function onDialogClose() {
if (dialog.value?.element) {
returnValue.value = dialog.value.element.returnValue;
}
}

</script>

<template>
  <div class="wrapper">
    <div>Returned Value: <span v-text="returnValue"></span></div>
    <VButton label="Open Dialog" appearance="outlined" @click="openDialog" />
  </div>
  <VDialog open ref="dialog" headline="Returning Dialog" @close="onDialogClose">
    <template #action-items>
      <VButton appearance="outlined" label="Cancel" @click="handleClick" />
      <VButton appearance="filled" label="Action" @click="handleClick" />
    </template>
  </VDialog>
</template>

<div class="wrapper">
  <div>
    Returned Value:
    <span id="dialog-output"></span>
  </div>
  <vwc-button label="Open Dialog" appearance="outlined" onclick="openDialog()"></vwc-button>
</div>
<vwc-dialog open headline="Returning Dialog">
  <vwc-button slot="action-items" appearance="outlined" label="Cancel"></vwc-button>
  <vwc-button slot="action-items" appearance="filled" label="Action"></vwc-button>
</vwc-dialog>

<script>
  (function handleReturnValue() {
    function handleClick(e) {
      buttonType = e.currentTarget.label;
      console.log(buttonType);
      dialog.returnValue = buttonType;
      dialog.open = false;
    }

    cancelButton = document.querySelector('[label="Cancel"]');
    actionButton = document.querySelector('[label="Action"]');
    dialog = document.querySelector('vwc-dialog');
    dialogOutput = document.querySelector('#dialog-output');

    cancelButton.onclick = actionButton.onclick = handleClick;
    dialog.addEventListener('close', (e) => (dialogOutput.innerText = dialog.returnValue));
    window.handleClick = handleClick;
  })();

  function openDialog() {
    document.querySelector('vwc-dialog').open = true;
  }
</script>

Slots

Icon Slot

Use the icon slot to display an icon from the icon library. The icon slot is the preferred way to add an icon to the component.

<script setup lang="ts">
import { VDialog, VIcon } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog headline="Dialog With Icon Slot" open icon-placement="side">
    <template #icon><VIcon name="info-line" label="Info" /></template>
  </VDialog>
</template>

Graphic Slot

Use the graphic slot in order to replace the icon.

The graphic slot overrides the icon property. Use the slot if a colored icon is needed or an icon with different dimensions.

<script setup lang="ts">
import { VDialog } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog headline="Dialog With Graphic Slot" open icon-placement="side">
    <template #graphic><img src="https://doodleipsum.com/40x40/hand-drawn?bg=7463D9&amp;i=af462b28146d2ac91599602e083ddee5" /></template>
  </VDialog>
</template>

<vwc-dialog headline="Dialog With Graphic Slot" open icon-placement="side">
  <img slot="graphic" src="https://doodleipsum.com/40x40/hand-drawn?bg=7463D9&amp;i=af462b28146d2ac91599602e083ddee5" />
</vwc-dialog>

Body Slot

Use the body slot in order to add custom HTML to the dialog.

When using body slot with a subtitle in the header, a separator will be added between the two.

<script setup lang="ts">
import { VButton, VDialog, VLayout, VTextField } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog open headline="Dialog Content" subtitle="Dialog with body content">
    <template #body>
      <VLayout gutters="small-block">
        <form>
          <VLayout column-basis="block">
            <VTextField label="Name" />
            <VTextField label="Password" type="password" />
            <VButton label="Login" appearance="filled" />
          </VLayout>
        </form>
      </VLayout>
    </template>
  </VDialog>
</template>

<vwc-dialog open headline="Dialog Content" subtitle="Dialog with body content">
  <vwc-layout slot="body" gutters="small-block">
    <form>
      <vwc-layout column-basis="block">
        <vwc-text-field label="Name"></vwc-text-field>
        <vwc-text-field label="Password" type="password"></vwc-text-field>
        <vwc-button label="Login" appearance="filled"></vwc-button>
      </vwc-layout>
    </form>
  </vwc-layout>
</vwc-dialog>

Full-Width-Body

To remove the body inline padding use full-width-body.
Use full-width-body if Progress-Bar or Tabs are needed in the Dialog.

<script setup lang="ts">
import { VDialog, VIcon, VLayout, VProgress, VTextArea, VTextField } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog open icon-placement="side" headline="Dialog Headline" full-width-body>
    <template #icon><VIcon name="info-line" label="Info" /></template>
    <template #body>
      <div class="dialog-body">
        <VProgress :min="0" :max="50" :value="12.5" shape="sharp" connotation="pacific" />
        <VLayout column-basis="block" gutters="medium-inline">
          <form>
            <VLayout column-basis="block">
              <VTextField label="Agent Name" placeholder="Search for an agent"
                ><template #icon><VIcon name="search-line" /></template
              ></VTextField>
              <VTextArea label="Additional Note (Optional)" />
            </VLayout>
          </form>
        </VLayout>
      </div>
    </template>
  </VDialog>
</template>

<style>
.dialog-body {
  display: flex;
  flex-direction: column;
  gap: 24px;
}
</style>

<vwc-dialog open icon-placement="side" headline="Dialog Headline" full-width-body>
  <vwc-icon slot="icon" name="info-line" label="Info"></vwc-icon>
  <div slot="body" class="dialog-body">
    <vwc-progress min="0" max="50" value="12.5" shape="sharp" connotation="pacific"></vwc-progress>
    <vwc-layout column-basis="block" gutters="medium-inline">
      <form>
        <vwc-layout column-basis="block">
          <vwc-text-field label="Agent Name" placeholder="Search for an agent"><vwc-icon slot="icon" name="search-line"></vwc-icon></vwc-text-field>
          <vwc-text-area label="Additional Note (Optional)"></vwc-text-area>
        </vwc-layout>
      </form>
    </vwc-layout>
  </div>
</vwc-dialog>

<style>
  .dialog-body {
    display: flex;
    flex-direction: column;
    gap: 24px;
  }
</style>

Action Items Slot

Use the action-items slot to add action items to the bottom of the dialog.

<script setup lang="ts">
import { VButton, VDialog } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog open headline="Dialog with primary and secondary actions" subtitle="This is an example of the dialog with slotted buttons">
    <template #action-items> <VButton slot="action-items" appearance="outlined" label="Cancel" /><VButton slot="action-items" appearance="filled" label="Action" /> </template>
  </VDialog>
</template>

<vwc-dialog open headline="Dialog with primary and secondary actions" subtitle="This is an example of the dialog with slotted buttons">
  <vwc-button slot="action-items" appearance="outlined" label="Cancel"></vwc-button>
  <vwc-button slot="action-items" appearance="filled" label="Action"></vwc-button>
</vwc-dialog>

Use the footer slot in order to add additional content to the bottom of the dialog.

When used in combination with action-items slot, the footer content will appear to the left of the action items.

<script setup lang="ts">
import { VButton, VCheckbox, VDialog } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog open headline="Dialog with footer" subtitle="This is an example of the dialog with a checkbox inside footer">
    <template #footer><VCheckbox slot="footer" label="I agree" /></template>
    <template #action-items><VButton appearance="filled" label="Ok" /></template>
  </VDialog>
</template>

<vwc-dialog open headline="Dialog with footer" subtitle="This is an example of the dialog with a checkbox inside footer">
  <vwc-checkbox slot="footer" label="I agree"></vwc-checkbox>
  <vwc-button slot="action-items" appearance="filled" label="Ok"></vwc-button>
</vwc-dialog>

Main Slot

Dialog has predefined content style template. Use the main slot to fully override a Dialog’s predefined template with your own.

<script setup lang="ts">
import { VDialog, VLayout } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog open>
    <template #main>
      <VLayout column-basis="block" gutters="medium"> Use main slot for your own layout and content </VLayout>
    </template>
  </VDialog>
</template>

CSS Variables

Z-index

Use --dialog-z-index for a different z-index value than 1.

z-index will affect only id the Dialog is not modal.

Inline min & max size

The dialog has default --dialog-min-inline-size and --dialog-max-inline-size values, which can be changed if needed.

Setting the same value for --dialog-min-inline-size and --dialog-max-inline-size will set a definitive width to the dialog.

When setting a new value for —dialog-min-inline-size and —dialog-max-inline-size take in consideration if different values are needed for mobile.

<script setup lang="ts">
import { VDialog, VIcon } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog class="dialog" headline="Headline" subtitle="Subtitle content" open>
    <template #icon><VIcon name="info-line" label="Info" /></template>
  </VDialog>
</template>

<style>
.dialog {
  --dialog-min-inline-size: 560px;
}
</style>

<vwc-dialog class="dialog" headline="Headline" subtitle="Subtitle content" open>
  <vwc-icon slot="icon" name="info-line" label="Info"></vwc-icon>
</vwc-dialog>

<style>
  .dialog {
    --dialog-min-inline-size: 560px;
  }
</style>

Block-Size

The dialog has a default --dialog-max-block-size. If the content is larger, the dialog will be scrollable.

<script setup lang="ts">
import { VDialog, VIcon } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog class="dialog" headline="Headline" subtitle="Subtitle content" open>
    <template #icon><VIcon name="info-line" label="Info" /></template>
  </VDialog>
</template>

<style>
.dialog {
  --dialog-max-block-size: 100px;
}
</style>

<vwc-dialog class="dialog" headline="Headline" subtitle="Subtitle content" open>
  <vwc-icon slot="icon" name="info-line" label="Info"></vwc-icon>
</vwc-dialog>

<style>
  .dialog {
    --dialog-max-block-size: 100px;
  }
</style>

Inset

When the dialog is not used as a modal, you can overwrite default inset values using --dialog-inset-inline and --dialog-inset-block variables.

<script setup lang="ts">
import { VDialog, VIcon } from '@vonage/vivid-api-vue';
</script>

<template>
  <VDialog class="dialog" headline="Headline" subtitle="Subtitle content" open>
    <template #icon><VIcon name="info-line" label="Info" /></template>
  </VDialog>
</template>

<style>
.dialog {
  --dialog-inset-inline: 50% 0;
  --dialog-inset-block: 24px 0;
}
</style>

<vwc-dialog class="dialog" headline="Headline" subtitle="Subtitle content" open>
  <vwc-icon slot="icon" name="info-line" label="Info"></vwc-icon>
</vwc-dialog>

<style>
  .dialog {
    --dialog-inset-inline: 50% 0;
    --dialog-inset-block: 24px 0;
  }
</style>

API Reference

Properties

Property	Type	Description
dismissButtonAriaLabel	`string`
fullWidthBody	`boolean`
headline	`string`
iconPlacement	`'top' \| 'side'`
modal	`boolean`	Sets the element's to be opened
noDismissButton	`boolean`	Remove the element's dismiss button
noDismissOnEsc	`boolean`	prevent a modal dialog from being dismissed by pressing esc
noLightDismiss	`boolean`	prevent a modal dialog from being dismissed by clicking outside of it.
nonDismissible	`boolean`	combines `no-light-dismiss`, `no-dismiss-on-esc`, and `no-dismiss-button`
open (open)	`boolean`	Sets the element's to be opened
returnValue	`string`
scrollableBody	`boolean`	Makes only the element's content area between the header and footer scrollable
subtitle	`string`

Property	Type	Description
dismiss-button-aria-label	`string`
full-width-body	`boolean`
headline	`string`
icon-placement	`'top' \| 'side'`
modal	`boolean`	Sets the element's to be opened
no-dismiss-button	`boolean`	Remove the element's dismiss button
no-dismiss-on-esc	`boolean`	prevent a modal dialog from being dismissed by pressing esc
no-light-dismiss	`boolean`	prevent a modal dialog from being dismissed by clicking outside of it.
non-dismissible	`boolean`	combines `no-light-dismiss`, `no-dismiss-on-esc`, and `no-dismiss-button`
open	`boolean`	Sets the element's to be opened
returnValue (property only)	`string`
scrollable-body	`boolean`	Makes only the element's content area between the header and footer scrollable
subtitle	`string`

Slots

Name	Description
action-items	Use the action-items slot in order to add action buttons to the bottom of the dialog.
body	Use the body slot in order to add custom HTML to the dialog.
footer	Use the footer slot in order to add action buttons to the bottom of the dialog.
graphic	Use the graphic slot in order to replace the icon.
icon	The preferred way to add an icon to the component.
main	Assign nodes to the main slot to fully override a dialog’s predefined flow and style with your own.

Name	Description
action-items	Use the action-items slot in order to add action buttons to the bottom of the dialog.
body	Use the body slot in order to add custom HTML to the dialog.
footer	Use the footer slot in order to add action buttons to the bottom of the dialog.
graphic	Use the graphic slot in order to replace the icon.
icon	The preferred way to add an icon to the component.
main	Assign nodes to the main slot to fully override a dialog’s predefined flow and style with your own.

Events

Name	Type	Description
cancel	`CustomEvent<undefined>`	The `cancel` event fires when the user requests to close the dialog. You can prevent the dialog from closing by calling `.preventDefault()` on the event.
close	`CustomEvent<string>`	The `close` event fires when the dialog closes (either via user interaction or via the API). It returns the return value inside the event's details property.
open	`CustomEvent<undefined>`	The `open` event fires when the dialog opens.

Name	Type	Description
cancel	`CustomEvent<undefined>`	The `cancel` event fires when the user requests to close the dialog. You can prevent the dialog from closing by calling `.preventDefault()` on the event.
close	`CustomEvent<string>`	The `close` event fires when the dialog closes (either via user interaction or via the API). It returns the return value inside the event's details property.
open	`CustomEvent<undefined>`	The `open` event fires when the dialog opens.

Methods

Name	Params	Returns	Description
close		`void`
show		`void`
showModal		`void`

Dialog

Usage

Modal

Open

Dismiss

No-light-dismiss

No-Dismiss-On-Esc

No-Dismiss-Button

Non-Dismissible

Dismiss-Button-Aria-Label

Return Value

Slots

Icon Slot

Graphic Slot

Body Slot

Full-Width-Body

Action Items Slot

Footer Slot

Main Slot

CSS Variables

Z-index

Inline min & max size

Block-Size

Inset

API Reference

Properties

Slots

Events

Methods