Skip to content

Dialog

See the Dialog guide for examples and configuration details.

Options

dialog

Can be set at: grid

Source code

dialog.dialog : boolean | object

The dialog option configures the Dialog plugin.

You can set the dialog option to one of the following:

SettingDescription
falseDisable the Dialog plugin
trueEnable the Dialog plugin with default options
dialog: Additional options
OptionPossible settingsDescription
templateObject with the template configuration (default: null).The template of the dialog allows to use prebuild templates
template.typeThe type of the template (‘confirm’)The type of the template
template.titleThe title of the templateThe title of the template
template.descriptionThe description of the templateThe description of the template
template.buttonsArray of objects with the buttons configuration (default: [])The buttons of the template
template.buttons.textThe text of the buttonThe text of the button
template.buttons.typeThe type of the button ('primary' | 'secondary')The type of the button
template.buttons.callbackThe callback function to trigger when the button is clickedThe callback function to trigger when the button is clicked
contentA string, HTMLElement or DocumentFragment (default: '')The content of the dialog
customClassNameA string (default: '')The custom class name of the dialog
backgroundOne of the options: 'solid' or 'semi-transparent' (default: 'solid')The background of the dialog
contentBackgroundBoolean (default: false)Whether to show the content background
animationBoolean (default: true)Whether to show the animation
closableBoolean (default: false)Whether to make the dialog closable
a11yObject with accessibility options (default: { role: 'dialog', ariaLabel: 'Dialog', ariaLabelledby: '', ariaDescribedby: '' })Accessibility options for the dialog
a11y.roleThe role of the dialog ('dialog' | 'alertdialog')The role of the dialog
a11y.ariaLabelThe label of the dialogThe label of the dialog
a11y.ariaLabelledbyThe ID of the element that labels the dialogThe ID of the element that labels the dialog
a11y.ariaDescribedbyThe ID of the element that describes the dialogThe ID of the element that describes the dialog

Read more:

This option can only be set at the grid level. It has no effect when set in the columns, cells, or cell options.

The dialog is available on the main grid only. In a grid nested in a cell, that is a cell of the handsontable, autocomplete, or dropdown cell type, this option has no effect.

Default: false
Since: 16.1.0
Example

// enable the Dialog plugin with default option
<HotTable
dialog={true}
/>
// enable the Dialog plugin with custom configuration
<HotTable
dialog={{
content: 'Dialog content',
customClassName: 'custom-dialog',
background: 'semi-transparent',
contentBackground: false,
animation: false,
closable: true,
a11y: {
role: 'dialog',
ariaLabel: 'Dialog',
ariaLabelledby: 'titleID',
ariaDescribedby: 'descriptionID',
}
}
}}
/>
// enable the Dialog plugin using a template
<HotTable
dialog={{
template: {
type: 'confirm',
title: 'Confirm',
description: 'Do you want change the value?',
}
}}
/>

Members

DEFAULT_SETTINGS

Source code

Dialog.DEFAULT_SETTINGS

Returns the default settings applied when the plugin is enabled without explicit configuration.

LICENSE

Source code

Dialog.LICENSE

Returns the license token of the plugin, its display name, where it is checked, and the tokens it requires.

PLUGIN_KEY

Source code

Dialog.PLUGIN_KEY

Returns the plugin key used to identify this plugin in Handsontable settings.

PLUGIN_PRIORITY

Source code

Dialog.PLUGIN_PRIORITY

Returns the priority order used to determine the order in which plugins are initialized.

SETTINGS_VALIDATORS

Source code

Dialog.SETTINGS_VALIDATORS

Returns validator functions for each plugin setting to verify their values are valid before applying them.

Methods

destroy

Source code

dialog.destroy()

Destroy dialog and reset plugin state.

disablePlugin

Source code

dialog.disablePlugin()

Disable plugin for this Handsontable instance.

enablePlugin

Source code

dialog.enablePlugin()

Enable plugin for this Handsontable instance.

focus

Source code

dialog.focus()

Focus the dialog.

hide

Source code

dialog.hide()

Hide the currently open dialog. Closes the dialog and restores the focus to the table.

isEnabled

Source code

dialog.isEnabled() ⇒ boolean

Check if the plugin is enabled in the handsontable settings.

The dialog renders into the ht-overlay element and registers a modal focus scope, and both belong to the main Handsontable instance. In a nested grid (the one the handsontable, autocomplete, and dropdown cell types create) neither exists, so the plugin stays disabled there.

The plugin is also enabled while another plugin requires it (the Loading plugin does, while it is enabled), even when the dialog option is off.

isVisible

Source code

dialog.isVisible() ⇒ boolean

Check if the dialog is currently visible.

Returns: boolean - True if the dialog is visible, false otherwise.

show

Source code

dialog.show(options)

Show dialog with given configuration. Displays the dialog with the specified content and options.

A dialog visible already is updated with the options, or, when they name content or template, replaced by the dialog they describe. A call made after the dialog hid shows a new dialog. When its options name content or template, it starts from the Options#dialog options alone. Otherwise, it shows the last dialog again with the options applied on top.

ParamTypeDescription
optionsobjectDialog configuration object containing content and display options.
options.templateobjectThe template to use for the dialog (default: null). An error is thrown when one call (together with the update() calls for the same dialog), or the Options#dialog option alone, sets both template and content. A content passed to this call replaces a template set in Options#dialog, and the other way around.
options.template.type'confirm'The type of the template (‘confirm’).
options.template.titlestringThe title of the dialog.
options.template.descriptionstringThe description of the dialog. Default: ”.
options.template.buttonsArray<object>The buttons to display in the dialog. Default: [].
options.template.buttons.textstringThe text of the button.
options.template.buttons.type'primary'
'secondary'
The type of the button.
options.template.buttons.callbackfunctionThe callback to trigger when the button is clicked.
options.contentstring
HTMLElement
DocumentFragment
The content to display in the dialog. Can be a string, HTMLElement, or DocumentFragment. Default: ”
options.customClassNamestringCustom CSS class name to apply to the dialog container. Default: ”
options.background'solid'
'semi-transparent'
Dialog background variant. Default: ‘solid’.
options.contentBackgroundbooleanWhether to show content background. Default: false.
options.animationbooleanWhether to enable animations when showing/hiding the dialog. Default: true.
options.closablebooleanWhether the dialog can be closed by user interaction. Default: false.
options.a11yobjectObject with accessibility options.
options.a11y.rolestringThe role of the dialog. Default: ‘dialog’.
options.a11y.ariaLabelstringThe label of the dialog. Default: ‘Dialog’.
options.a11y.ariaLabelledbystringThe ID of the element that labels the dialog. Default: ”.
options.a11y.ariaDescribedbystringThe ID of the element that describes the dialog. Default: ”.

showAlert

Source code

dialog.showAlert(message, [callback])

Displays the alert dialog with the specified content.

ParamTypeDescription
messagestring
Object
The message to display in the dialog. Can be a string or an object with title and description properties.
[callback]functionoptional The callback to trigger when the button is clicked. The dialog stays open until you call Dialog#hide, usually from this callback.

showConfirm

Source code

dialog.showConfirm(message, [onOk], [onCancel])

Displays the confirm dialog with the specified content and options.

ParamTypeDescription
messagestring
Object
The message to display in the dialog. Can be a string or an object with title and description properties.
[onOk]functionoptional The callback to trigger when the OK button is clicked.
[onCancel]functionoptional The callback to trigger when the Cancel button is clicked. The dialog stays open until you call Dialog#hide, usually from these callbacks.

update

Source code

dialog.update(options)

Update the dialog configuration.

The first call after the dialog hid prepares a new dialog: when its options name content or template, it starts from the Options#dialog options alone. Later calls add to that dialog.

ParamTypeDescription
optionsobjectDialog configuration object containing content and display options.
options.templateobjectThe template to use for the dialog (default: null). An error is thrown when one dialog’s own options (its show() and update() calls), or the Options#dialog option alone, set both template and content. A content passed here replaces a template set in Options#dialog, and the other way around.
options.template.type'confirm'The type of the template (‘confirm’).
options.template.titlestringThe title of the dialog.
options.template.descriptionstringThe description of the dialog. Default: ”.
options.template.buttonsArray<object>The buttons to display in the dialog. Default: [].
options.template.buttons.textstringThe text of the button.
options.template.buttons.type'primary'
'secondary'
The type of the button.
options.template.buttons.callbackfunctionThe callback to trigger when the button is clicked.
options.contentstring
HTMLElement
DocumentFragment
The content to display in the dialog. Can be a string, HTMLElement, or DocumentFragment. Default: ”
options.customClassNamestringCustom CSS class name to apply to the dialog container. Default: ”
options.background'solid'
'semi-transparent'
Dialog background variant. Default: ‘solid’.
options.contentBackgroundbooleanWhether to show content background. Default: false.
options.animationbooleanWhether to enable animations when showing/hiding the dialog. Default: true.
options.closablebooleanWhether the dialog can be closed by user interaction. Default: false.
options.a11yobjectObject with accessibility options.
options.a11y.rolestringThe role of the dialog. Default: ‘dialog’.
options.a11y.ariaLabelstringThe label of the dialog. Default: ‘Dialog’.
options.a11y.ariaLabelledbystringThe ID of the element that labels the dialog. Default: ”.
options.a11y.ariaDescribedbystringThe ID of the element that describes the dialog. Default: ”.

updatePlugin

Source code

dialog.updatePlugin()

Update plugin state after Handsontable settings update. The plugin stays enabled, so a dialog on screen stays there and shows the new dialog options under the options it was shown with, and no beforeDialogHide or afterDialogHide fires for it. A dialog whose description did not change is not rendered again, and one that did keeps the focus on the same control. Turning the option off goes through disablePlugin() instead, which hides the dialog.