JavaScript Data GridEmpty 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
Basic configuration
Custom configuration
Dynamic messages based on source
Localize empty data state
Related API reference

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.

{
    "name": "handsontable",
    "version": "1.0.0",
    "description": "",
    "dependencies": {
      "hyperformula": "^3.0.0",
      "handsontable": "16.2"
    }
  }

<!DOCTYPE html>
  <html>
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Handsontable</title>
    </head>
  
    <body>
      <div id="example1" class="hot"></div>
    </body>
  </html>

import './styles.css'
import Handsontable from 'handsontable';
import 'handsontable/dist/handsontable.full.min.css';

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

new Handsontable(container, {
  themeName: 'ht-theme-main',
  data: [],
  height: 'auto',
  colHeaders: true,
  rowHeaders: true,
  navigableHeaders: true,
  dropdownMenu: true,
  filters: true,
  emptyDataState: true,
  licenseKey: 'non-commercial-and-evaluation',
});

import Handsontable from 'handsontable';
import 'handsontable/dist/handsontable.full.min.css';

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

new Handsontable(container, {
  themeName: 'ht-theme-main',
  data: [],
  height: 'auto',
  colHeaders: true,
  rowHeaders: true,
  navigableHeaders: true,
  dropdownMenu: true,
  filters: true,
  emptyDataState: true,
  licenseKey: 'non-commercial-and-evaluation',
});

<script src="https://cdn.jsdelivr.net/npm/handsontable@16.2/dist/handsontable.full.min.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@16.2/styles/handsontable.min.css" /> 
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@16.2/styles/ht-theme-main.css" /> 
<script src="https://handsontable.com/docs/scripts/fixer.js"></script>

<div id="example1" class="hot"></div>

Custom configuration

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

{
    "name": "handsontable",
    "version": "1.0.0",
    "description": "",
    "dependencies": {
      "hyperformula": "^3.0.0",
      "handsontable": "16.2"
    }
  }

<!DOCTYPE html>
  <html>
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Handsontable</title>
    </head>
  
    <body>
      <div id="example2" class="hot"></div>
    </body>
  </html>

import './styles.css'
// Custom configuration example for Empty Data State plugin
// This example shows how to customize the empty data state message
import Handsontable from 'handsontable';
import 'handsontable/dist/handsontable.full.min.css';

const container = document.getElementById('example2');
const hot = new Handsontable(container, {
  themeName: 'ht-theme-main',
  data: [],
  height: 'auto',
  colHeaders: ['First Name', 'Last Name', 'Email'],
  rowHeaders: true,
  navigableHeaders: true,
  dropdownMenu: true,
  filters: true,
  emptyDataState: {
    message: {
      title: 'No data available',
      description: 'Please add some data to get started.',
      buttons: [
        {
          text: 'Add Sample Data',
          type: 'primary',
          callback: () => {
            // Add some sample data
            hot.loadData([
              ['John', 'Doe', 'john@example.com'],
              ['Jane', 'Smith', 'jane@example.com'],
              ['Bob', 'Johnson', 'bob@example.com'],
              ['Alice', 'Johnson', 'alice@example.com'],
            ]);
          },
        },
      ],
    },
  },
  licenseKey: 'non-commercial-and-evaluation',
});

// Custom configuration example for Empty Data State plugin
// This example shows how to customize the empty data state message
import Handsontable from 'handsontable';
import 'handsontable/dist/handsontable.full.min.css';

const container = document.getElementById('example2');
const hot = new Handsontable(container, {
  themeName: 'ht-theme-main',
  data: [],
  height: 'auto',
  colHeaders: ['First Name', 'Last Name', 'Email'],
  rowHeaders: true,
  navigableHeaders: true,
  dropdownMenu: true,
  filters: true,
  emptyDataState: {
    message: {
      title: 'No data available',
      description: 'Please add some data to get started.',
      buttons: [
        {
          text: 'Add Sample Data',
          type: 'primary',
          callback: () => {
            // Add some sample data
            hot.loadData([
              ['John', 'Doe', 'john@example.com'],
              ['Jane', 'Smith', 'jane@example.com'],
              ['Bob', 'Johnson', 'bob@example.com'],
              ['Alice', 'Johnson', 'alice@example.com'],
            ]);
          },
        },
      ],
    },
  },
  licenseKey: 'non-commercial-and-evaluation',
});

<script src="https://cdn.jsdelivr.net/npm/handsontable@16.2/dist/handsontable.full.min.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@16.2/styles/handsontable.min.css" /> 
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@16.2/styles/ht-theme-main.css" /> 
<script src="https://handsontable.com/docs/scripts/fixer.js"></script>

<div id="example2" class="hot"></div>

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.

{
    "name": "handsontable",
    "version": "1.0.0",
    "description": "",
    "dependencies": {
      "hyperformula": "^3.0.0",
      "handsontable": "16.2"
    }
  }

<!DOCTYPE html>
  <html>
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Handsontable</title>
    </head>
  
    <body>
      <div id="example3" class="hot"></div>
    </body>
  </html>

import './styles.css'
// Dynamic messages based on source example for Empty Data State plugin
// This example shows how to provide different messages based on the source of empty state
import Handsontable from 'handsontable';
import 'handsontable/dist/handsontable.full.min.css';

const container = document.getElementById('example3');
const hot = new Handsontable(container, {
  themeName: 'ht-theme-main',
  data: [],
  height: 'auto',
  colHeaders: ['First Name', 'Last Name', 'Email'],
  rowHeaders: true,
  navigableHeaders: true,
  dropdownMenu: true,
  filters: true,
  contextMenu: true,
  emptyDataState: {
    message: (source) => {
      switch (source) {
        case 'filters':
          return {
            title: 'No results found',
            description: 'Your current filters are hiding all results. Try adjusting your search criteria.',
            buttons: [
              {
                text: 'Clear Filters',
                type: 'secondary',
                callback: () => {
                  const filtersPlugin = hot.getPlugin('filters');

                  if (filtersPlugin) {
                    filtersPlugin.clearConditions();
                    filtersPlugin.filter();
                  }
                },
              },
            ],
          };
        default:
          return {
            title: 'No data available',
            description: "There's nothing to display yet. Add some data to get started.",
            buttons: [
              {
                text: 'Add Sample Data',
                type: 'primary',
                callback: () => {
                  hot.loadData([
                    ['John', 'Doe', 'john@example.com'],
                    ['Jane', 'Smith', 'jane@example.com'],
                    ['Bob', 'Johnson', 'bob@example.com'],
                    ['Alice', 'Johnson', 'alice@example.com'],
                  ]);
                },
              },
            ],
          };
      }
    },
  },
  licenseKey: 'non-commercial-and-evaluation',
});

// Dynamic messages based on source example for Empty Data State plugin
// This example shows how to provide different messages based on the source of empty state
import Handsontable from 'handsontable';
import 'handsontable/dist/handsontable.full.min.css';

const container = document.getElementById('example3');
const hot = new Handsontable(container, {
  themeName: 'ht-theme-main',
  data: [],
  height: 'auto',
  colHeaders: ['First Name', 'Last Name', 'Email'],
  rowHeaders: true,
  navigableHeaders: true,
  dropdownMenu: true,
  filters: true,
  contextMenu: true,
  emptyDataState: {
    message: (source) => {
      switch (source) {
        case 'filters':
          return {
            title: 'No results found',
            description: 'Your current filters are hiding all results. Try adjusting your search criteria.',
            buttons: [
              {
                text: 'Clear Filters',
                type: 'secondary',
                callback: () => {
                  const filtersPlugin = hot.getPlugin('filters');

                  if (filtersPlugin) {
                    filtersPlugin.clearConditions();
                    filtersPlugin.filter();
                  }
                },
              },
            ],
          };
        default:
          return {
            title: 'No data available',
            description: "There's nothing to display yet. Add some data to get started.",
            buttons: [
              {
                text: 'Add Sample Data',
                type: 'primary',
                callback: () => {
                  hot.loadData([
                    ['John', 'Doe', 'john@example.com'],
                    ['Jane', 'Smith', 'jane@example.com'],
                    ['Bob', 'Johnson', 'bob@example.com'],
                    ['Alice', 'Johnson', 'alice@example.com'],
                  ]);
                },
              },
            ],
          };
      }
    },
  },
  licenseKey: 'non-commercial-and-evaluation',
});

<script src="https://cdn.jsdelivr.net/npm/handsontable@16.2/dist/handsontable.full.min.js"></script>
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@16.2/styles/handsontable.min.css" /> 
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@16.2/styles/ht-theme-main.css" /> 
<script src="https://handsontable.com/docs/scripts/fixer.js"></script>

<div id="example3" class="hot"></div>

// Dynamic messages based on source example for Empty Data State plugin
// This example shows how to provide different messages based on the source of empty state
import Handsontable from 'handsontable';
import 'handsontable/dist/handsontable.full.min.css';

const container = document.getElementById('example3');
const hot = new Handsontable(container, {
  themeName: 'ht-theme-main',
  data: [],
  height: 'auto',
  colHeaders: ['First Name', 'Last Name', 'Email'],
  rowHeaders: true,
  navigableHeaders: true,
  dropdownMenu: true,
  filters: true,
  contextMenu: true,
  emptyDataState: {
    message: (source) => {
      switch (source) {
        case 'filters':
          return {
            title: 'No results found',
            description: 'Your current filters are hiding all results. Try adjusting your search criteria.',
            buttons: [
              {
                text: 'Clear Filters',
                type: 'secondary',
                callback: () => {
                  const filtersPlugin = hot.getPlugin('filters');

                  if (filtersPlugin) {
                    filtersPlugin.clearConditions();
                    filtersPlugin.filter();
                  }
                },
              },
            ],
          };
        default:
          return {
            title: 'No data available',
            description: "There's nothing to display yet. Add some data to get started.",
            buttons: [
              {
                text: 'Add Sample Data',
                type: 'primary',
                callback: () => {
                  hot.loadData([
                    ['John', 'Doe', 'john@example.com'],
                    ['Jane', 'Smith', 'jane@example.com'],
                    ['Bob', 'Johnson', 'bob@example.com'],
                    ['Alice', 'Johnson', 'alice@example.com'],
                  ]);
                },
              },
            ],
          };
      }
    },
  },
  licenseKey: 'non-commercial-and-evaluation',
});

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.