Modal
#

modaldialogwindow

Classic modal overlay which represents a dialog box or other interactive component, such as a dismissible alert, sub-window, etc.

Examples
#

Overview
#

va-modal, by default, has the OK and Cancel buttons in the footer. You can provide a custom message and title with the message and title props respectively.

va-modal supports close on Esc (enabled by default) and close on overlay click (enabled by default). These features may be disabled by setting the props no-esc-dismiss and no-outside-dismiss respectively, or no-dismiss as a shorthand to disable both of them.

Stateful
#

By default va-modal is stateless. You can change it by setting the stateful prop.

Full screen
#

Add the fullscreen prop to cover the whole page.

Note that va-modal is full screen on mobile viewports by default. You can change it by setting the mobile-fullscreen prop to false.

Close button
#

By default modal can be closed by clicking on the overlay or pressing the Esc key. You can add a close button by setting the close-button prop to true.

Modal methods
#

There are several methods that you can employ to toggle the visibility of va-modal.

v-model property is always automatically synced with va-modal visible state and you can show/hide using v-model.

You can access modal using ref attribute and then call the show(), hide() or toggle() methods.

Before close
#

You can set custom before-close prop to dynamically prevent modal from closing. Function accept hide method, so you can call it whenever you need. This way you can make API calls or show additional confirm window before closing modal.

Blurred overlay
#

Use the blur CSS filter for the overlay layer by setting the blur property to true. You can override the root CSS variable --va-modal-overlay-background-blur-radius to set your own blur radius.

Hiding the overlay
#

Hide the modal's overlay via setting the overlay prop to false.

Note that clicking outside of the modal will still close the modal even though the overlay is hidden. You can disable this behavior by setting the no-outside-dismiss prop on va-modal.

Disable open and close animation
#

To disable the transition/animation when modal opens and closes, set the prop without-transitions.

Scrolling long content
#

When modals become too long for the user's viewport or device, they allow the scrolling of the modal body. Try the demo below to see what we mean.

You can also allow scrolling only content in modal via setting the fixed-layout prop. Title and actions will be fixed.

Customization
#

va-modal provides several slots (default, header and footer), that you can use to customize the content of various sections of the modal.

You can set custom text for Cancel and Ok buttons via ok-text and cancel-text props respectively, or you can hide them via hide-default-actions prop.

va-modal also supports custom overlay-opacity as well as z-index, max-width and max-height for a modal.

Using the anchor slot, the user can access the show(), hide() and toggle() methods.

You can remove default padding with no-padding prop and change default action buttons with content slot.

Modal sizing
#

Modals have three optional sizes, available via the prop size. These sizes kick in at certain breakpoints to avoid horizontal scrollbars on narrower viewports. Valid optional sizes are small, medium (default), and large.

Nested modals
#

Modals can be nested: you can open one modal from another.

API
#

Name	Description	Types	Default
allowBodyScroll	Allows the document scroll while modal is open.	`Boolean`	`false`
anchorClass	Set class name to the `anchor` slot container	`String`	-
ariaCloseLabel	The aria-label of the close button	`String`	`"$t:close"`
attachElement	A valid selector of element, where modal will be rendered	`String`	`"body"`
backgroundColor	The background color of the modal dialog	`String`	`"background-secondary"`
beforeCancel	Function run before canceling modal (after pressing ESC, clicking on overlay or clicking cancel button) and can prevent closing. First argument is `hide` function, so you can close modal manually	`Function`	-
beforeClose	Function run before closing modal and can prevent closing. First argument is `hide` function, so you can close modal manually	`Function`	-
beforeOk	Function run before clicking on OK button and can prevent closing. First argument is `hide` function, so you can close modal manually	`Function`	-
blur	Use `blur` filter to overlay. Root `css` variable `--va-modal-overlay-background-blur-radius` sets the blur radius	`Boolean`	`false`
cancelText	Text string to place in the default footer Cancel button	`String`	`"$t:cancel"`
child:cancelButton		`Object`	-
child:closeButton		`Object`	-
child:okButton		`Object`	-
closeButton		`Boolean`	`false`
disableAttachment	Ignore `attach-element` prop and render component as it's parent child	`Boolean`	`false`
fixedLayout	Use `fixed-layout: true` to scroll only content in modal. Title and actions will be fixed	`Boolean`	`false`
fullscreen	Add the `fullscreen` prop to cover the whole page	`Boolean`	`false`
hideDefaultActions	Use `hide-default-actions: true` to hide Cancel and Ok buttons	`Boolean`	`false`
maxHeight	Use `max-height` to change the maximum height of the modal. If content is larger, scroll will appear	`String`	`""`
maxWidth	Use `max-width` to change the maximum width of the modal.	`String`	`""`
message	Content of modal body	`String`	`""`
mobileFullscreen	Use `mobile-fullscreen: false` to disable fullscreen mode for mobile viewports	`Boolean`	`true`
modelValue	The value of the `v-model` bindings.	`Boolean`	`false`
noDismiss	Disable both close on overlay click and close on Esc	`Boolean`	`false`
noEscDismiss	Disable close on Esc	`Boolean`	`false`
noOutsideDismiss	Disable close on overlay click	`Boolean`	`false`
noPadding	Disable padding in the modal dialog	`Boolean`	`false`
okText	Text string to place in the default footer Ok button	`String`	`"$t:ok"`
overlay	Use `overlay: false` to hide the overlay	`Boolean`	`true`
overlayOpacity	Set the overlay's opacity	`Number \| String`	`0.6`
showNestedOverlay		`Boolean`	`false`
size	Set the size of the modal's width. `"small"`, `"medium"` (default) or `"large"`	`String`	`"medium"`
sizesConfig	Provide a set of sizes as a global component specific setting.	`Object`	`{ "defaultSize": "medium", "sizes": { "small": 576, "medium": 768, "large": 992, "auto": "max-content" } }`
stateful	Add possibility to work with component without setting `v-model`.	`Boolean`	`false`
title	Text content to place in the title	`String`	`""`
withoutTransitions	Use `without-transitions: true` to turn off the open and close animations on the modal	`Boolean`	`false`
zIndex	Set the modal's `z-index`	`Number \| String`	-

Name	Description
beforeClose	Emits before modal's start closing after transition started. The event argument is: `(el: HTMLElement) => void`
beforeOpen	Emits before modal's open after transition started. The event argument is: `(el: HTMLElement) => void`
cancel	Emits when the user closes the modal window without side effects. The event argument is: `() => void`
clickOutside	Emits when overlay is clicked. The event argument is: `() => void`
close	Emits when modal's is closed and transition is complete. The event argument is: `(el: HTMLElement) => void`
ok	Emits when Ok button is clicked. The event argument is: `() => void`
open	Emits when modal's is open and transition is complete. The event argument is: `(el: HTMLElement) => void`
update:modelValue	The event is triggered when the component needs to change visibility

Name	Description
anchor	Modal anchor content. There is access to the `show`, `hide` and `toggle` methods in the slots scope
default	Content of modal body
footer	Modal footer content
header	Modal header content

Name	Description
hide	Hide modal (change `modelValue`)
show	Show modal (change `modelValue`)
toggle	Toggle a modal's visibility (change `modelValue`)

Name	Default Value
--va-modal-title-margin-bottom	1.5rem
--va-modal-position	fixed
--va-modal-top	0
--va-modal-left	0
--va-modal-display	flex
--va-modal-width	100%
--va-modal-height	100%
--va-modal-align-items	center
--va-modal-justify-content	center
--va-modal-overflow	hidden
--va-modal-outline	0
--va-modal-z-index	unset
--va-modal-container-z-index	100
--va-modal-basic-duration	0.3s
--va-modal-opacity-transition	calc(var(--va-modal-basic-duration) * 0.5) cubic-bezier(1, 0.5, 0.8, 1)
--va-modal-transform-transition	var(--va-modal-basic-duration) ease
--va-modal-overlay-background-blur-radius	4px
--va-modal-padding	var(--va-modal-padding-top) var(--va-modal-padding-right) var(--va-modal-padding-bottom) var(--va-modal-padding-left)
--va-modal-padding-top	1.5rem
--va-modal-padding-right	1.5rem
--va-modal-padding-bottom	1.5rem
--va-modal-padding-left	1.5rem
--va-modal-dialog-min-height	3.125rem
--va-modal-dialog-height	fit-content
--va-modal-dialog-border-radius	0.375rem
--va-modal-dialog-margin	1rem
--va-modal-dialog-box-shadow	0 4px 70px -18px var(--va-shadow)
--va-modal-overlay-opacity-transition	opacity calc(2 * var(--va-modal-basic-duration) / 3) cubic-bezier(1, 0.5, 0.8, 1)
--va-modal-overlay-color	rgb(0, 0, 0)
--va-modal-overlay-opacity	0.6
--va-modal-overlay-nested-opacity	0.1
--va-modal-footer-justify-content	flex-end

Modal functional API
#

To make it easier to create modal we have a shorthands. For options API it is $vaModal that provides the VaModalPlugin (automatically installed with createVuestic). For composition Api we have useModal hook. Hook and global object have similar API.

options Api

composition Api

export default {
  methods: {
    onOkCallback() { ... },
    onCancelCallback() { ... },
    onButtonClick() {
      this.$vaModal.init({
        message: 'Modal example!',
        onOk: this.onOkCallback,
        onCancel: this.onCancelCallback,
      })
    },
  },
}

Methods
#

Method name	Api Type	Description
init(options: string \| ModalOptions)	Options \| Composition	Creates new modal instance. Returns modal instance VNode

Options
#

type	type
title	`string`
message	`string`
attachElement	`string`
disableAttachElement	`boolean`
okText	`string`
cancelText	`string`
hideDefaultActions	`boolean`
fullscreen	`boolean`
mobileFullscreen	`boolean`
noDismiss	`boolean`
noOutsideDismiss	`boolean`
noEscDismiss	`boolean`
maxWidth	`string`
maxHeight	`string`
size	`small \| medium \| large`
fixedLayout	`boolean`
withoutTransitions	`boolean`
overlay	`boolean`
overlayOpacity	`number \| string`
zIndex	`number \| string`
onOk	`() => void`
onCancel	`() => void`
onClickOutside	`() => void`
onUpdate:modelValue	`(value: boolean) => void`
onOpen	`(el: HTMLElement) => void`
onClose	`(el: HTMLElement) => void`

Modal
#

Examples
#

Overview
#

Stateful
#

Full screen
#

Close button
#

Modal methods
#

Before close
#

Blurred overlay
#

Hiding the overlay
#

Disable open and close animation
#

Scrolling long content
#

Customization
#

Modal sizing
#

Nested modals
#

API
#

Props #

Events #

Slots #

Methods #

Css Variables #

Modal functional API
#

Methods
#

Options
#

Modal #

Examples #

Overview #

Stateful #

Full screen #

Close button #

Modal methods #

Before close #

Blurred overlay #

Hiding the overlay #

Disable open and close animation #

Scrolling long content #

Customization #

Modal sizing #

Nested modals #

API #

Props #

Events #

Slots #

Methods #

Css Variables #

Modal functional API #

Methods #

Options #

Modal
#

Examples
#

Overview
#

Stateful
#

Full screen
#

Close button
#

Modal methods
#

Before close
#

Blurred overlay
#

Hiding the overlay
#

Disable open and close animation
#

Scrolling long content
#

Customization
#

Modal sizing
#

Nested modals
#

API
#

Modal functional API
#

Methods
#

Options
#