EmptyDataState

Plugin: EmptyDataState

Description

The empty data state plugin provides a empty data state overlay system for Handsontable. It displays a empty data state overlay with customizable message.

In order to enable the empty data state mechanism, Options#emptyDataState option must be set to true.

When [[Options#dataProvider]] is enabled, the loading overlay is toggled from DataProvider fetch hooks ([[Hooks#beforeDataProviderFetch]], [[Hooks#afterDataProviderFetch]], [[Hooks#afterDataProviderFetchError]]).

The plugin provides several configuration options to customize the empty data state behavior and appearance:

• message: Message to display in the empty data state overlay.
  • title: Title to display in the empty data state overlay.
  • description: Description to display in the empty data state overlay.
  • buttons: Buttons to display in the empty data state overlay.
    • text: Text to display in the button.
    • type: Type of the button.
    • callback: Callback function to call when the button is clicked.

Example

// Enable empty data state plugin with default messages
hotSettings: Handsontable.GridSettings = {
  emptyDataState: true
}

// Enable empty data state plugin with custom message
hotSettings: Handsontable.GridSettings = {
  emptyDataState: {
    message: 'No data available'
  }
}

// Enable empty data state plugin with custom message and buttons for any source
hotSettings: Handsontable.GridSettings = {
  emptyDataState: {
    message: {
      title: 'No data available',
      description: 'There’s nothing to display yet.',
      buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }],
    },
  },
},

// Enable empty data state plugin with custom message and buttons for specific source
hotSettings: Handsontable.GridSettings = {
  emptyDataState: {
    message: (source) => {
      switch (source) {
        case "filters":
          return {
            title: 'No data available for filters',
            description: 'There’s nothing to display yet.',
            buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }],
          };
        case "loading":
          return {
            title: 'Loading data',
            description: 'Please wait.',
          };
        default:
          return {
            title: 'No data available',
            description: 'There’s nothing to display yet.',
          };
      }
    }
  }
}

<hot-table [settings]="hotSettings"></hot-table>

Options

emptyDataState

Source code

emptyDataState.emptyDataState : boolean | object

The emptyDataState option configures the EmptyDataState plugin.

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

Setting	Description
false	Disable the EmptyDataState plugin
true	Enable the EmptyDataState plugin
An object	Enable the EmptyDataState plugin with custom settings

If you set the emptyDataState option to an object, you can configure the following settings:

Property	Possible values	Description
message	string | object | function	Message to display in the empty data state overlay.

If you set the message option to an object, it have following properties:

Property	Possible values	Description
title	string	Title to display in the empty data state overlay.
description	string	Description to display in the empty data state overlay.
buttons	array	Buttons to display in the empty data state overlay.
loading	boolean	When true, shows a loading spinner (used for server fetch state).

If you set the message option to a function, the source argument can be "unknown", "filters", or "loading". With [[Options#dataProvider]], the "loading" branch follows DataProvider fetch hooks (beforeDataProviderFetch, afterDataProviderFetch, and related hooks) using the same rules as server-backed loading in the DataProvider plugin. Internal refetches (for example after column sort or CRUD) set skipLoading on [[Hooks#beforeDataProviderFetch]] so the EmptyDataState plugin can omit the loading overlay for those requests.

If you set the buttons option to an array, each item requires following properties:

Property	Possible values	Description
text	string	Text to display in the button.
type	’primary’ | ‘secondary’	Type of the button.
callback	function	Callback function to call when the button is clicked.

Read more:

• Plugins: EmptyDataState

Default: false
Since: 16.2.0
Example

// Enable empty data state plugin with default messages
emptyDataState: true,

// Enable empty data state plugin with custom message
emptyDataState: {
  message: 'No data available',
},

// Enable empty data state plugin with custom message and buttons for any source
emptyDataState: {
  message: {
    title: 'No data available',
    description: 'There’s nothing to display yet.',
    buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }],
  },
},

// Enable empty data state plugin with custom message and buttons for specific source
emptyDataState: {
  message: (source) => {
    switch (source) {
      case "filters":
        return {
          title: 'No data available',
          description: 'There’s nothing to display yet.',
          buttons: [{ text: 'Reset filters', type: 'secondary', callback: () => {} }],
        };
      case "loading":
        return {
          title: 'Loading data',
          description: 'Please wait.',
        };
      default:
        return {
          title: 'No data available',
          description: 'There’s nothing to display yet.',
        };
    }
  },
},

Methods

destroy

Source code

emptyDataState.destroy()

Destroy plugin instance.

disablePlugin

Source code

emptyDataState.disablePlugin()

Disable plugin for this Handsontable instance.

enablePlugin

Source code

emptyDataState.enablePlugin()

Enable plugin for this Handsontable instance.

isEnabled

Source code

emptyDataState.isEnabled() ⇒ boolean

Check if the plugin is enabled in the handsontable settings.

isVisible

Source code

emptyDataState.isVisible() ⇒ boolean

Check if the plugin is currently visible.

updatePlugin

Source code

emptyDataState.updatePlugin()

Update plugin state after Handsontable settings update.