Empty Data State

Display empty data state overlays and provide user feedback when your data grid has no data to display using the Empty Data State plugin.

Overview

The Empty Data State plugin provides a user-friendly overlay system for Handsontable when there’s no data to display. It automatically detects when your table is empty or when all data is hidden by filters, and displays an appropriate message with optional action buttons.

With simplicity and effectiveness in mind, the empty data state plugin was designed to provide a consistent user experience with customizable appearance and behavior. It automatically integrates with the Filters plugin to provide context-aware messages and actions.

Basic configuration

To enable the Empty Data State plugin, set the emptyDataState option to true or provide a configuration object.

1
import Handsontable from 'handsontable';
2

3
const container = document.getElementById('example1');
4

5
new Handsontable(container, {
6
  data: [],
7
  height: 'auto',
8
  colHeaders: true,
9
  rowHeaders: true,
10
  navigableHeaders: true,
11
  dropdownMenu: true,
12
  filters: true,
13
  emptyDataState: true,
14
  licenseKey: 'non-commercial-and-evaluation',
15
});

1
import Handsontable from 'handsontable';
2

3
const container = document.getElementById('example1') as HTMLElement;
4

5
new Handsontable(container, {
6
  data: [], // Empty data to trigger empty state
7
  height: 'auto',
8
  colHeaders: true,
9
  rowHeaders: true,
10
  navigableHeaders: true,
11
  dropdownMenu: true,
12
  filters: true,
13
  emptyDataState: true, // Enable empty data state with default settings
14
  licenseKey: 'non-commercial-and-evaluation',
15
});

Custom configuration

The empty data state supports customization of the title, description, and action buttons.

1
// Custom configuration example for Empty Data State plugin
2
// This example shows how to customize the empty data state message
3
import Handsontable from 'handsontable';
4

5
const container = document.getElementById('example2');
6
const hot = new Handsontable(container, {
7
  data: [],
8
  height: 'auto',
9
  colHeaders: ['First Name', 'Last Name', 'Email'],
10
  rowHeaders: true,
11
  navigableHeaders: true,
12
  dropdownMenu: true,
13
  filters: true,
14
  emptyDataState: {
15
    message: {
16
      title: 'No data available',
17
      description: 'Please add some data to get started.',
18
      buttons: [
19
        {
20
          text: 'Add Sample Data',
21
          type: 'primary',
22
          callback: () => {
23
            // Add some sample data
24
            hot.loadData([
25
              ['John', 'Doe', 'john@example.com'],
26
              ['Jane', 'Smith', 'jane@example.com'],
27
              ['Bob', 'Johnson', 'bob@example.com'],
28
              ['Alice', 'Johnson', 'alice@example.com'],
29
            ]);
30
          },
31
        },
32
      ],
33
    },
34
  },
35
  licenseKey: 'non-commercial-and-evaluation',
36
});

1
// Custom configuration example for Empty Data State plugin
2
// This example shows how to customize the empty data state message
3

4
import Handsontable from 'handsontable';
5

6
const container = document.getElementById('example2') as HTMLElement;
7

8
const hot = new Handsontable(container, {
9
  data: [], // Empty data to trigger empty state
10
  height: 'auto',
11
  colHeaders: ['First Name', 'Last Name', 'Email'],
12
  rowHeaders: true,
13
  navigableHeaders: true,
14
  dropdownMenu: true,
15
  filters: true,
16
  emptyDataState: {
17
    message: {
18
      title: 'No data available',
19
      description: 'Please add some data to get started.',
20
      buttons: [
21
        {
22
          text: 'Add Sample Data',
23
          type: 'primary',
24
          callback: () => {
25
            // Add some sample data
26
            hot.loadData([
27
              ['John', 'Doe', 'john@example.com'],
28
              ['Jane', 'Smith', 'jane@example.com'],
29
              ['Bob', 'Johnson', 'bob@example.com'],
30
              ['Alice', 'Johnson', 'alice@example.com'],
31
            ]);
32
          },
33
        },
34
      ],
35
    },
36
  },
37
  licenseKey: 'non-commercial-and-evaluation',
38
});

Dynamic messages based on source

You can provide different messages based on the source of the empty state (e.g., filters vs. no data). This allows for more contextual user guidance.

1
// Dynamic messages based on source example for Empty Data State plugin
2
// This example shows how to provide different messages based on the source of empty state
3
import Handsontable from 'handsontable';
4

5
const container = document.getElementById('example3');
6
const hot = new Handsontable(container, {
7
  data: [],
8
  height: 'auto',
9
  colHeaders: ['First Name', 'Last Name', 'Email'],
10
  rowHeaders: true,
11
  navigableHeaders: true,
12
  dropdownMenu: true,
13
  filters: true,
14
  contextMenu: true,
15
  emptyDataState: {
16
    message: (source) => {
17
      switch (source) {
18
        case 'filters':
19
          return {
20
            title: 'No results found',
21
            description: 'Your current filters are hiding all results. Try adjusting your search criteria.',
22
            buttons: [
23
              {
24
                text: 'Clear Filters',
25
                type: 'secondary',
26
                callback: () => {
27
                  const filtersPlugin = hot.getPlugin('filters');
28

29
                  if (filtersPlugin) {
30
                    filtersPlugin.clearConditions();
31
                    filtersPlugin.filter();
32
                  }
33
                },
34
              },
35
            ],
36
          };
37
        default:
38
          return {
39
            title: 'No data available',
40
            description: "There's nothing to display yet. Add some data to get started.",
41
            buttons: [
42
              {
43
                text: 'Add Sample Data',
44
                type: 'primary',
45
                callback: () => {
46
                  hot.loadData([
47
                    ['John', 'Doe', 'john@example.com'],
48
                    ['Jane', 'Smith', 'jane@example.com'],
49
                    ['Bob', 'Johnson', 'bob@example.com'],
50
                    ['Alice', 'Johnson', 'alice@example.com'],
51
                  ]);
52
                },
53
              },
54
            ],
55
          };
56
      }
57
    },
58
  },
59
  licenseKey: 'non-commercial-and-evaluation',
60
});

1
// Dynamic messages based on source example for Empty Data State plugin
2
// This example shows how to provide different messages based on the source of empty state
3

4
import Handsontable from 'handsontable';
5

6
const container = document.getElementById('example3') as HTMLElement;
7

8
const hot = new Handsontable(container, {
9
  data: [],
10
  height: 'auto',
11
  colHeaders: ['First Name', 'Last Name', 'Email'],
12
  rowHeaders: true,
13
  navigableHeaders: true,
14
  dropdownMenu: true,
15
  filters: true,
16
  contextMenu: true,
17
  emptyDataState: {
18
    message: (source: string) => {
19
      switch (source) {
20
        case 'filters':
21
          return {
22
            title: 'No results found',
23
            description: 'Your current filters are hiding all results. Try adjusting your search criteria.',
24
            buttons: [
25
              {
26
                text: 'Clear Filters',
27
                type: 'secondary',
28
                callback: () => {
29
                  const filtersPlugin = hot.getPlugin('filters');
30

31
                  if (filtersPlugin) {
32
                    filtersPlugin.clearConditions();
33
                    filtersPlugin.filter();
34
                  }
35
                },
36
              },
37
            ],
38
          };
39
        default:
40
          return {
41
            title: 'No data available',
42
            description: "There's nothing to display yet. Add some data to get started.",
43
            buttons: [
44
              {
45
                text: 'Add Sample Data',
46
                type: 'primary',
47
                callback: () => {
48
                  hot.loadData([
49
                    ['John', 'Doe', 'john@example.com'],
50
                    ['Jane', 'Smith', 'jane@example.com'],
51
                    ['Bob', 'Johnson', 'bob@example.com'],
52
                    ['Alice', 'Johnson', 'alice@example.com'],
53
                  ]);
54
                },
55
              },
56
            ],
57
          };
58
      }
59
    },
60
  },
61
  licenseKey: 'non-commercial-and-evaluation',
62
});

Localize empty data state

Translate default empty data state labels using the global translations mechanism. The empty data state plugin introduces the following keys to the language dictionary that you can use to translate the empty state UI:

Key	Default Value
`EMPTY_DATA_STATE_TITLE`	`'No data available'`
`EMPTY_DATA_STATE_DESCRIPTION`	`'There's nothing to display yet.'`
`EMPTY_DATA_STATE_TITLE_FILTERS`	`'No results found'`
`EMPTY_DATA_STATE_DESCRIPTION_FILTERS`	`'It looks like your current filters are hiding all results.'`
`EMPTY_DATA_STATE_BUTTONS_FILTERS_RESET`	`'Reset filters'`

To learn more about the translation mechanism, see the Languages guide.

emptyDataStateOptions

EmptyDataStatePlugins

FiltersPlugins