Empty Data State

Use the EmptyDataState plugin to display a contextual overlay when the grid has no data or all rows are hidden by active filters.

Prerequisites

To use the Empty Data State plugin, import it from Handsontable:

To use the filter-aware empty state (which automatically detects when all rows are hidden by filters), also enable the Filters plugin alongside emptyDataState.

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. 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 React, { useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotTableRef = useRef(null);
10

11
  return (
12
    <HotTable
13
      ref={hotTableRef}
14
      data={[]} // Empty data to trigger empty state
15
      height="auto"
16
      colHeaders={true}
17
      rowHeaders={true}
18
      navigableHeaders={true}
19
      dropdownMenu={true}
20
      filters={true}
21
      emptyDataState={true} // Enable empty data state with default settings
22
      licenseKey="non-commercial-and-evaluation"
23
    />
24
  );
25
};
26

27
export default ExampleComponent;

1
import React, { useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotTableRef = useRef(null);
10

11
  return (
12
    <HotTable
13
      ref={hotTableRef}
14
      data={[]} // Empty data to trigger empty state
15
      height="auto"
16
      colHeaders={true}
17
      rowHeaders={true}
18
      navigableHeaders={true}
19
      dropdownMenu={true}
20
      filters={true}
21
      emptyDataState={true} // Enable empty data state with default settings
22
      licenseKey="non-commercial-and-evaluation"
23
    />
24
  );
25
};
26

27
export default ExampleComponent;

Custom configuration

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

1
import React, { useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotTableRef = useRef(null);
10

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

47
export default ExampleComponent;

1
import React, { useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotTableRef = useRef(null);
10

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

47
export default ExampleComponent;

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
import React, { useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotTableRef = useRef(null);
10

11
  return (
12
    <HotTable
13
      ref={hotTableRef}
14
      data={[]} // Empty data to trigger empty state
15
      height="auto"
16
      colHeaders={['First Name', 'Last Name', 'Email']}
17
      rowHeaders={true}
18
      navigableHeaders={true}
19
      dropdownMenu={true}
20
      filters={true}
21
      contextMenu={true}
22
      emptyDataState={{
23
        message: (source) => {
24
          switch (source) {
25
            case 'filters':
26
              return {
27
                title: 'No results found',
28
                description: 'Your current filters are hiding all results. Try adjusting your search criteria.',
29
                buttons: [
30
                  {
31
                    text: 'Clear Filters',
32
                    type: 'secondary',
33
                    callback: () => {
34
                      const filtersPlugin = hotTableRef.current?.hotInstance.getPlugin('filters');
35

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

71
export default ExampleComponent;

1
import React, { useRef } from 'react';
2
import { HotTable } from '@handsontable/react-wrapper';
3
import { registerAllModules } from 'handsontable/registry';
4

5
// register Handsontable's modules
6
registerAllModules();
7

8
const ExampleComponent = () => {
9
  const hotTableRef = useRef(null);
10

11
  return (
12
    <HotTable
13
      ref={hotTableRef}
14
      data={[]} // Empty data to trigger empty state
15
      height="auto"
16
      colHeaders={['First Name', 'Last Name', 'Email']}
17
      rowHeaders={true}
18
      navigableHeaders={true}
19
      dropdownMenu={true}
20
      filters={true}
21
      contextMenu={true}
22
      emptyDataState={{
23
        message: (source) => {
24
          switch (source) {
25
            case 'filters':
26
              return {
27
                title: 'No results found',
28
                description: 'Your current filters are hiding all results. Try adjusting your search criteria.',
29
                buttons: [
30
                  {
31
                    text: 'Clear Filters',
32
                    type: 'secondary',
33
                    callback: () => {
34
                      const filtersPlugin = hotTableRef.current?.hotInstance.getPlugin('filters');
35

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

71
export default ExampleComponent;

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.

Result

After enabling the plugin, the grid displays a centered overlay message whenever there is no data to show. When the Filters plugin is also enabled, the overlay automatically switches to a filter-specific message and shows a “Reset filters” button when all rows are hidden by active filter conditions.

emptyDataStateOptions

EmptyDataStatePlugins

FiltersPlugins