JavaScript Data GridPlugin: Dialog

On this page

• Description
• Options
  • dialog
• Methods
  • destroy
  • disablePlugin
  • enablePlugin
  • focus
  • hide
  • isEnabled
  • isVisible
  • show
  • update
  • updatePlugin

Description

The dialog plugin provides a modal dialog system for Handsontable. It allows you to display custom content in modal dialogs that overlay the table, providing a way to show notifications, error messages, loading indicators, or any other interactive content.

In order to enable the dialog mechanism, Options#dialog option must be set to true.

The plugin provides several configuration options to customize the dialog behavior and appearance:

• content: The string or HTMLElement content to display in the dialog (default: '')
• customClassName: Custom class name to apply to the dialog (default: '')
• background: Dialog background variant 'solid' | 'semi-transparent' (default: 'solid')
• contentBackground: Whether to show content background (default: false)
• animation: Whether to enable animations (default: true)
• closable: Whether the dialog can be closed (default: false)
• a11y: Object with accessibility options (default object below)

{
  role: 'dialog', // Role of the dialog 'dialog' | 'alertdialog' (default: 'dialog')
  ariaLabel: 'Dialog', // Label for the dialog (default: 'Dialog')
  ariaLabelledby: '', // ID of the element that labels the dialog (default: '')
  ariaDescribedby: '', // ID of the element that describes the dialog (default: ''),
}

Example

// Enable dialog plugin with default options
dialog: true,

// Enable dialog plugin with custom configuration
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',
  }
}

// Access to dialog plugin instance:
const dialogPlugin = hot.getPlugin('dialog');

// Show a dialog programmatically:
dialogPlugin.show({
   content: '<h2>Custom Dialog</h2><p>This is a custom dialog content.</p>',
   closable: true,
});

// Hide the dialog programmatically:
dialogPlugin.hide();

// Check if dialog is visible:
const isVisible = dialogPlugin.isVisible();

Options

dialog

Source code

dialog.dialog : boolean | object

The dialog option configures the Dialog plugin.

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

Setting	Description
false	Disable the Dialog plugin
true	Enable the Dialog plugin with default options

dialog: Additional options

Option	Possible settings	Description
content	A string, HTMLElement or DocumentFragment (default: '')	The content of the dialog
customClassName	A string (default: '')	The custom class name of the dialog
background	One of the options: 'solid' or 'semi-transparent' (default: 'solid')	The background of the dialog
contentBackground	Boolean (default: false)	Whether to show the content background
animation	Boolean (default: true)	Whether to show the animation
closable	Boolean (default: false)	Whether to make the dialog closable
a11y	Object with accessibility options (default: { role: 'dialog', ariaLabel: 'Dialog', ariaLabelledby: '', ariaDescribedby: '' })	Accessibility options for the dialog

Read more:

• Plugins: Dialog

Default: false
Since: 16.1.0
Example

// enable the Dialog plugin with default option
dialog: true,

// enable the Dialog plugin with custom configuration
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',
  }
}

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.

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.

Param	Type	Description
options	object	Dialog configuration object containing content and display options.
options.content	string HTMLElement DocumentFragment	The content to display in the dialog. Can be a string, HTMLElement, or DocumentFragment. Default: ''
options.customClassName	string	Custom CSS class name to apply to the dialog container. Default: ''
options.background	'solid' 'semi-transparent'	Dialog background variant. Default: 'solid'.
options.contentBackground	boolean	Whether to show content background. Default: false.
options.animation	boolean	Whether to enable animations when showing/hiding the dialog. Default: true.
options.closable	boolean	Whether the dialog can be closed by user interaction. Default: false.
options.a11y	object	Object with accessibility options.
options.a11y.role	string	The role of the dialog. Default: 'dialog'.
options.a11y.ariaLabel	string	The label of the dialog. Default: 'Dialog'.
options.a11y.ariaLabelledby	string	The ID of the element that labels the dialog. Default: ''.
options.a11y.ariaDescribedby	string	The ID of the element that describes the dialog. Default: ''.

update

Source code

dialog.update(options)

Update the dialog configuration.

Param	Type	Description
options	object	Dialog configuration object containing content and display options.
options.content	string HTMLElement DocumentFragment	The content to display in the dialog. Can be a string, HTMLElement, or DocumentFragment. Default: ''
options.customClassName	string	Custom CSS class name to apply to the dialog container. Default: ''
options.background	'solid' 'semi-transparent'	Dialog background variant. Default: 'solid'.
options.contentBackground	boolean	Whether to show content background. Default: false.
options.animation	boolean	Whether to enable animations when showing/hiding the dialog. Default: true.
options.closable	boolean	Whether the dialog can be closed by user interaction. Default: false.
options.a11y	object	Object with accessibility options.
options.a11y.role	string	The role of the dialog. Default: 'dialog'.
options.a11y.ariaLabel	string	The label of the dialog. Default: 'Dialog'.
options.a11y.ariaLabelledby	string	The ID of the element that labels the dialog. Default: ''.
options.a11y.ariaDescribedby	string	The ID of the element that describes the dialog. Default: ''.

updatePlugin

Source code

dialog.updatePlugin()

Update plugin state after Handsontable settings update.