Cell renderer

Create a custom cell renderer function, to have full control over how a cell looks.

Overview

A renderer is a function that determines how a cell looks. It’s responsible for the complete cell rendering process, including DOM structure creation, content insertion, applying CSS classes, setting accessibility attributes, and managing all visual aspects of the cell.

Tip

If you only need to format the displayed value (e.g., add units, format dates, or apply text transformations), consider using the valueFormatter option instead. It's more performant and simpler for value-only transformations. Use a renderer when you need to modify the DOM structure, add custom HTML elements, or handle complex visual layouts. See the renderer vs valueFormatter section for a detailed comparison.

Built-in renderers

Handsontable provides 10 built-in renderers that you can use by their alias names. Each renderer is designed for a specific use case:

Alias	What the renderer does
autocomplete	Renders autocomplete cells with suggestions
checkbox	Renders checkbox cells for boolean values or values defined by checkedTemplate and uncheckedTemplate options
date	Renders date values with date formatting
dropdown	Renders dropdown cells with select options
html	Renders HTML content in cells (allows raw HTML)
numeric	Renders numeric values with number formatting
password	Renders password fields (masks the displayed value)
text	Renders plain text (default renderer)
time	Renders time values with time formatting

Using aliases provides a convenient way to specify which renderer should be used without needing to reference the full renderer function. You can change the renderer function associated with an alias without modifying the code that uses it.

renderer vs valueFormatter

As mentioned in the Overview, Handsontable provides two distinct options for controlling how cell values are displayed: valueFormatter and renderer. This section provides a detailed comparison to help you choose the right tool for your use case.

What is renderer?

The renderer option is a function responsible for the complete cell rendering process. It handles DOM structure creation, content insertion (via innerText or innerHTML), applying CSS classes, setting accessibility attributes, and managing all visual aspects of the cell.

Function signature:

renderer(hotInstance, td, row, col, prop, value, cellProperties)

When to use renderer:

• Modify DOM structure (add icons, custom HTML elements, complex layouts)
• Apply custom styling or CSS classes dynamically
• Handle accessibility attributes
• Create interactive elements within cells
• When you need full control over the cell’s HTML structure

Example:

function customRenderer(hotInstance, td, row, col, prop, value, cellProperties) {
  // Create custom DOM structure
  td.innerHTML = `
    <div class="custom-wrapper">
      <span class="icon">📊</span>
      <span class="value">${value}</span>
    </div>
  `;
}

What is valueFormatter?

The valueFormatter option (available since v17.0.0) is a function that transforms cell values before they are displayed. It focuses solely on value transformation and is called by the rendering engine right before the renderer function executes.

Function signature:

valueFormatter(value, cellProperties) => formattedValue

When to use valueFormatter:

• Transform displayed values (add prefix, suffix, units)
• Format dates, numbers, or text in a custom way
• Apply simple text transformations
• When you only need to change what is displayed, not how it’s rendered

Example:

columns={[{
  data: 'price',
  valueFormatter(value) {
    return value ? `$${value.toFixed(2)}` : '';
  }
}]}

Key differences

Aspect	valueFormatter	renderer
Purpose	Transform the value	Complete cell rendering
Scope	Value transformation only	DOM structure, styling, accessibility
Performance	Faster (called before renderer)	More overhead (full DOM manipulation)
Use case	Simple formatting (units, prefixes)	Complex layouts, custom HTML
Returns	Formatted value	Nothing (modifies DOM directly)

Using renderer and valueFormatter together

Using both renderer and valueFormatter together is recommended when you need both value formatting and custom DOM structure. This approach separates concerns: valueFormatter handles value transformation, while renderer focuses on DOM manipulation. This separation improves maintainability and code clarity. The valueFormatter executes first, transforming the value, and then the renderer receives the formatted value:

columns={[{
  data: 'amount',
  valueFormatter(value) {
    return `$${value.toFixed(2)}`;
  },
  renderer(hotInstance, TD, row, col, prop, value, cellProperties) {
    TD.innerHTML = `<div class="amount-cell"><span class="currency">${value}</span></div>`;
  }
}]}

In this example, valueFormatter adds the currency symbol and formatting, while renderer wraps it in a custom DOM structure with additional styling.

Use a cell renderer

You can use any of the built-in renderers by specifying their alias name in your column configuration. The example below shows how to use the numeric renderer, which formats numeric values according to the cell’s formatting options:

<HotTable
  data={someData}
  columns={[
    {
      renderer: "numeric",
    },
  ]}
/>

Declare a custom renderer as a component

Handsontable’s React wrapper lets you create custom cell renderers using React components.

To use your component as a Handsontable renderer, pass it in the renderer prop if either HotTable or HotColumn components, as you would with any other config option.

Tip

Handsontable's autoRowSize and autoColumnSize options require calculating the widths/heights of some of the cells before rendering them into the table. For this reason, it's not currently possible to use them alongside component-based renderers, as they're created after the table's initialization.

Be sure to turn those options off in your Handsontable configuration, as keeping them enabled may cause unexpected results. Please note that autoColumnSize is enabled by default.

Source code

JavaScript

import { HotTable, HotColumn } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// Register all Handsontable's modules.
registerAllModules();

// your renderer component
const RendererComponent = (props) => {
  // the available renderer-related props are:
  // - `row` (row index)
  // - `col` (column index)
  // - `prop` (column property name)
  // - `TD` (the HTML cell element)
  // - `cellProperties` (the `cellProperties` object for the edited cell)
  return (
    <>
      <i style={{ color: '#a9a9a9' }}>
        Row: {props.row}, column: {props.col},
      </i>{' '}
      value: {props.value}
    </>
  );
};

const hotData = [
  ['A1', 'B1', 'C1', 'D1', 'E1'],
  ['A2', 'B2', 'C2', 'D2', 'E2'],
  ['A3', 'B3', 'C3', 'D3', 'E3'],
  ['A4', 'B4', 'C4', 'D4', 'E4'],
  ['A5', 'B5', 'C5', 'D5', 'E5'],
  ['A6', 'B6', 'C6', 'D6', 'E6'],
  ['A7', 'B7', 'C7', 'D7', 'E7'],
  ['A8', 'B8', 'C8', 'D8', 'E8'],
  ['A9', 'B9', 'C9', 'D9', 'E9'],
];

const ExampleComponent = () => {
  return (
    <HotTable
      data={hotData}
      autoWrapRow={true}
      autoWrapCol={true}
      autoRowSize={false}
      autoColumnSize={false}
      height="auto"
      licenseKey="non-commercial-and-evaluation"
    >
      <HotColumn width={250} renderer={RendererComponent} />
    </HotTable>
  );
};

export default ExampleComponent;

TypeScript

import { HotTable, HotColumn } from '@handsontable/react-wrapper';
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';

// Register all Handsontable's modules.
registerAllModules();

type RendererProps = {
  TD?: HTMLTableCellElement;
  value?: string | number;
  row?: number;
  col?: number;
  cellProperties?: Handsontable.CellProperties;
};

// your renderer component
const RendererComponent = (props: RendererProps) => {
  // the available renderer-related props are:
  // - `row` (row index)
  // - `col` (column index)
  // - `prop` (column property name)
  // - `TD` (the HTML cell element)
  // - `cellProperties` (the `cellProperties` object for the edited cell)
  return (
    <>
      <i style={{ color: '#a9a9a9' }}>
        Row: {props.row}, column: {props.col},
      </i>{' '}
      value: {props.value}
    </>
  );
};

const hotData = [
  ['A1', 'B1', 'C1', 'D1', 'E1'],
  ['A2', 'B2', 'C2', 'D2', 'E2'],
  ['A3', 'B3', 'C3', 'D3', 'E3'],
  ['A4', 'B4', 'C4', 'D4', 'E4'],
  ['A5', 'B5', 'C5', 'D5', 'E5'],
  ['A6', 'B6', 'C6', 'D6', 'E6'],
  ['A7', 'B7', 'C7', 'D7', 'E7'],
  ['A8', 'B8', 'C8', 'D8', 'E8'],
  ['A9', 'B9', 'C9', 'D9', 'E9'],
];

const ExampleComponent = () => {
  return (
    <HotTable
      data={hotData}
      autoWrapRow={true}
      autoWrapCol={true}
      autoRowSize={false}
      autoColumnSize={false}
      height="auto"
      licenseKey="non-commercial-and-evaluation"
    >
      <HotColumn width={250} renderer={RendererComponent} />
    </HotTable>
  );
};

export default ExampleComponent;

Use the renderer component within React’s Context

In this example, React’s Context passes information available in the main app component to the renderer. In this case, we’re using just the renderer, but the same principle works with editors as well.

Source code

JavaScript

import { useState, useContext, createContext } from 'react';
import { HotTable, HotColumn } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// Register all Handsontable's modules.
registerAllModules();

// a component
const HighlightContext = createContext(false);

// a renderer component
function CustomRenderer(props) {
  const darkMode = useContext(HighlightContext);

  if (!props.TD) return;

  if (darkMode) {
    props.TD.className = 'dark';
  } else {
    props.TD.className = '';
  }

  return <div>{props.value}</div>;
}

const ExampleComponent = () => {
  const [darkMode, setDarkMode] = useState(false);
  const toggleDarkMode = (event) => {
    setDarkMode(event.target.checked);
  };

  return (
    <HighlightContext.Provider value={darkMode}>
      <div className="controls">
        <label>
          <input type="checkbox" onClick={toggleDarkMode} /> Dark mode
        </label>
      </div>
      <HotTable
        data={[['A1'], ['A2'], ['A3'], ['A4'], ['A5'], ['A6'], ['A7'], ['A8'], ['A9'], ['A10']]}
        rowHeaders={true}
        autoRowSize={false}
        autoColumnSize={false}
        height="auto"
        licenseKey={'non-commercial-and-evaluation'}
      >
        <HotColumn renderer={CustomRenderer} />
      </HotTable>
    </HighlightContext.Provider>
  );
};

export default ExampleComponent;

TypeScript

import { useState, useContext, MouseEvent, createContext } from 'react';
import { HotTable, HotColumn } from '@handsontable/react-wrapper';
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';

// Register all Handsontable's modules.
registerAllModules();

type RendererProps = {
  TD?: HTMLTableCellElement;
  value?: string | number;
  row?: number;
  col?: number;
  cellProperties?: Handsontable.CellProperties;
};

// a component
const HighlightContext = createContext(false);

// a renderer component
function CustomRenderer(props: RendererProps) {
  const darkMode = useContext(HighlightContext);

  if (!props.TD) return;

  if (darkMode) {
    props.TD.className = 'dark';
  } else {
    props.TD.className = '';
  }

  return <div>{props.value}</div>;
}

const ExampleComponent = () => {
  const [darkMode, setDarkMode] = useState(false);

  const toggleDarkMode = (event: MouseEvent) => {
    setDarkMode((event.target as HTMLInputElement).checked);
  };

  return (
    <HighlightContext.Provider value={darkMode}>
      <div className="controls">
        <label>
          <input type="checkbox" onClick={toggleDarkMode} /> Dark mode
        </label>
      </div>
      <HotTable
        data={[['A1'], ['A2'], ['A3'], ['A4'], ['A5'], ['A6'], ['A7'], ['A8'], ['A9'], ['A10']]}
        rowHeaders={true}
        autoRowSize={false}
        autoColumnSize={false}
        height="auto"
        licenseKey={'non-commercial-and-evaluation'}
      >
        <HotColumn renderer={CustomRenderer} />
      </HotTable>
    </HighlightContext.Provider>
  );
};

export default ExampleComponent;

CSS

#example2 .handsontable td.dark {
  background: #000 !important;
  color: #fff !important;
}

#example2 .handsontable td {
  background: #fff !important;
  color: #000 !important;
}

Declare a custom renderer as a function

You can also declare a custom renderer for the HotTable component by declaring it as a function. In the simplest scenario, you can pass the rendering function as the hotRenderer prop into HotTable or HotColumn. If you need the renderer to be a part of a columns config array, declare it under the renderer key.

The following example implements @handsontable/react-wrapper with a custom renderer added to one of the columns. It takes an image URL as the input and renders the image in the edited cell.

Source code

JavaScript

import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  return (
    <HotTable
      id="hot"
      data={[
        ['A1', '/docs/img/examples/professional-javascript-developers-nicholas-zakas.jpg'],
        ['A2', '/docs/img/examples/javascript-the-good-parts.jpg'],
      ]}
      columns={[
        {},
        {
          renderer(instance, td, row, col, prop, value, cellProperties) {
            const img = document.createElement('img');

            img.src = value;
            img.addEventListener('mousedown', (event) => {
              event.preventDefault();
            });
            td.innerText = '';
            td.appendChild(img);

            return td;
          },
        },
      ]}
      colHeaders={true}
      rowHeights={55}
      height="auto"
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};

export default ExampleComponent;

TypeScript

import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  return (
    <HotTable
      id="hot"
      data={[
        ['A1', '/docs/img/examples/professional-javascript-developers-nicholas-zakas.jpg'],
        ['A2', '/docs/img/examples/javascript-the-good-parts.jpg'],
      ]}
      columns={[
        {},
        {
          renderer(instance, td, row, col, prop, value, cellProperties) {
            const img = document.createElement('img');

            img.src = value;

            img.addEventListener('mousedown', (event) => {
              event.preventDefault();
            });

            td.innerText = '';
            td.appendChild(img);

            return td;
          },
        },
      ]}
      colHeaders={true}
      rowHeights={55}
      height="auto"
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};

export default ExampleComponent;

Tip

All the sections below describe how to utilize the features available for the Handsontable function-based renderers.

Register custom cell renderer

To register your own alias use registerRenderer() function from the @handsontable/renderers package. It takes two arguments:

• rendererName - a string representing a renderer function
• renderer - a renderer function that will be represented by rendererName

If you’d like to register asteriskDecoratorRenderer under alias asterisk you have to call:

import { registerRenderer } from "@handsontable/renderers";

registerRenderer("asterisk", asteriskDecoratorRenderer);

Choose aliases wisely. If you register your renderer under name that is already registered, the target function will be overwritten:

import { registerRenderer } from "@handsontable/renderers";

registerRenderer("text", asteriskDecoratorRenderer);

Now "text" alias points to asteriskDecoratorRenderer function, not the built-in textRenderer.

So, unless you intentionally want to overwrite an existing alias, try to choose a unique name. A good practice is prefixing your aliases with some custom name (for example your GitHub username) to minimize the possibility of name collisions. This is especially important if you want to publish your renderer, because you never know aliases has been registered by the user who uses your renderer.

import { registerRenderer } from "@handsontable/renderers";

registerRenderer("asterisk", asteriskDecoratorRenderer);

Someone might already registered such alias

import { registerRenderer } from "@handsontable/renderers";

registerRenderer("my.asterisk", asteriskDecoratorRenderer);

That’s better.

Use an alias

The final touch is to use registered aliases. That way users can easily refer to an alias without the need to know the name of the function.

To sum up, a well prepared renderer function should look like this:

import { registerRenderer } from "@handsontable/renderers";

function customRenderer(
  hotInstance,
  td,
  row,
  column,
  prop,
  value,
  cellProperties
) {
  // ...your custom logic of the renderer
}

// Register an alias
registerRenderer("my.custom", customRenderer);

From now on, you can use customRenderer like so:

<HotTable
  data={someData}
  columns={[
    {
      renderer: "my.custom",
    },
  ]}
/>

Render custom HTML in cells

This example shows how to use custom cell renderers to display HTML content in a cell. This is a very powerful feature. Just remember to escape any HTML code that could be used for XSS attacks. In the below configuration:

Deprecated

**DOMPurify will be removed in the next version.** After that, any string containing HTML will be stripped before rendering. To keep sanitized HTML (e.g. with DOMPurify), set the sanitizer option to your own sanitizer function.

• Title column uses built-in HTML renderer that allows any HTML. This is unsafe if your code comes from untrusted source. Take notice that a Handsontable user can use it to enter <script> or other potentially malicious tags using the cell editor!
• Description column also uses HTML renderer (same as above)
• Comments column uses a custom renderer (safeHtmlRenderer). This should be safe for user input, because only certain tags are allowed
• Cover column accepts image URL as a string and converts it to a <img> in the renderer

Source code

JavaScript

import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  const data = [
    {
      title:
        '<a href="https://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691">Professional JavaScript for Web Developers</a>',
      description:
        'This <a href="https://bit.ly/sM1bDf">book</a> provides a developer-level introduction along with more advanced and useful features of <b>JavaScript</b>.',
      comments: 'I would rate it ★★★★☆',
      cover: '/docs/img/examples/professional-javascript-developers-nicholas-zakas.jpg',
    },
    {
      title: '<a href="https://shop.oreilly.com/product/9780596517748.do">JavaScript: The Good Parts</a>',
      description:
        'This book provides a developer-level introduction along with <b>more advanced</b> and useful features of JavaScript.',
      comments: 'This is the book about JavaScript',
      cover: '/docs/img/examples/javascript-the-good-parts.jpg',
    },
    {
      title: '<a href="https://shop.oreilly.com/product/9780596805531.do">JavaScript: The Definitive Guide</a>',
      description:
        '<em>JavaScript: The Definitive Guide</em> provides a thorough description of the core <b>JavaScript</b> language and both the legacy and standard DOMs implemented in web browsers.',
      comments:
        'I\'ve never actually read it, but the <a href="https://shop.oreilly.com/product/9780596805531.do">comments</a> are highly <strong>positive</strong>.',
      cover: '/docs/img/examples/javascript-the-definitive-guide.jpg',
    },
  ];

  function safeHtmlRenderer(_instance, td, _row, _col, _prop, value, _cellProperties) {
    // WARNING: Be sure you only allow certain HTML tags to avoid XSS threats.
    // Sanitize the "value" before passing it to the innerHTML property.
    td.innerHTML = value;
  }

  function coverRenderer(_instance, td, _row, _col, _prop, value, _cellProperties) {
    const img = document.createElement('img');

    img.src = value;
    img.addEventListener('mousedown', (event) => {
      event.preventDefault();
    });
    td.innerText = '';
    td.appendChild(img);

    return td;
  }

  return (
    <HotTable
      data={data}
      colWidths={[200, 200, 200, 80]}
      colHeaders={['Title', 'Description', 'Comments', 'Cover']}
      height="auto"
      columns={[
        { data: 'title', renderer: 'html' },
        { data: 'description', renderer: 'html' },
        { data: 'comments', renderer: safeHtmlRenderer },
        { data: 'cover', renderer: coverRenderer },
      ]}
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};

export default ExampleComponent;

TypeScript

import { HotTable } from '@handsontable/react-wrapper';
import Handsontable from 'handsontable/base';
import { registerAllModules } from 'handsontable/registry';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  const data = [
    {
      title:
        '<a href="https://www.amazon.com/Professional-JavaScript-Developers-Nicholas-Zakas/dp/1118026691">Professional JavaScript for Web Developers</a>',
      description:
        'This <a href="https://bit.ly/sM1bDf">book</a> provides a developer-level introduction along with more advanced and useful features of <b>JavaScript</b>.',
      comments: 'I would rate it ★★★★☆',
      cover: '/docs/img/examples/professional-javascript-developers-nicholas-zakas.jpg',
    },
    {
      title: '<a href="https://shop.oreilly.com/product/9780596517748.do">JavaScript: The Good Parts</a>',
      description:
        'This book provides a developer-level introduction along with <b>more advanced</b> and useful features of JavaScript.',
      comments: 'This is the book about JavaScript',
      cover: '/docs/img/examples/javascript-the-good-parts.jpg',
    },
    {
      title: '<a href="https://shop.oreilly.com/product/9780596805531.do">JavaScript: The Definitive Guide</a>',
      description:
        '<em>JavaScript: The Definitive Guide</em> provides a thorough description of the core <b>JavaScript</b> language and both the legacy and standard DOMs implemented in web browsers.',
      comments:
        'I\'ve never actually read it, but the <a href="https://shop.oreilly.com/product/9780596805531.do">comments</a> are highly <strong>positive</strong>.',
      cover: '/docs/img/examples/javascript-the-definitive-guide.jpg',
    },
  ];

  function safeHtmlRenderer(
    _instance: Handsontable,
    td: HTMLTableCellElement,
    _row: number,
    _col: number,
    _prop: string | number,
    value: Handsontable.CellValue,
    _cellProperties: Handsontable.CellProperties
  ) {
    // WARNING: Be sure you only allow certain HTML tags to avoid XSS threats.
    // Sanitize the "value" before passing it to the innerHTML property.
    td.innerHTML = value;
  }

  function coverRenderer(
    _instance: Handsontable,
    td: HTMLTableCellElement,
    _row: number,
    _col: number,
    _prop: string | number,
    value: Handsontable.CellValue,
    _cellProperties: Handsontable.CellProperties
  ) {
    const img = document.createElement('img');

    img.src = value;

    img.addEventListener('mousedown', (event) => {
      event.preventDefault();
    });

    td.innerText = '';
    td.appendChild(img);

    return td;
  }

  return (
    <HotTable
      data={data}
      colWidths={[200, 200, 200, 80]}
      colHeaders={['Title', 'Description', 'Comments', 'Cover']}
      height="auto"
      columns={[
        { data: 'title', renderer: 'html' },
        { data: 'description', renderer: 'html' },
        { data: 'comments', renderer: safeHtmlRenderer },
        { data: 'cover', renderer: coverRenderer },
      ]}
      autoWrapRow={true}
      autoWrapCol={true}
      licenseKey="non-commercial-and-evaluation"
    />
  );
};

export default ExampleComponent;

Render custom HTML in header

You can also put HTML into row and column headers. If you need to attach events to DOM elements like the checkbox below, just remember to identify the element by class name, not by id. This is because row and column headers are duplicated in the DOM tree and id attribute must be unique.

Deprecated

**DOMPurify will be removed in the next version.** After that, any string containing HTML will be stripped before rendering. To keep sanitized HTML (e.g. with DOMPurify), set the sanitizer option to your own sanitizer function.

Source code

JavaScript

import { useRef } from 'react';
import { HotTable } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import { textRenderer } from 'handsontable/renderers/textRenderer';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  const hotRef = useRef(null);
  let isChecked = false;

  function customRenderer(_instance, td) {
    textRenderer.apply(this, arguments);

    if (isChecked) {
      td.style.backgroundColor = 'yellow';
    } else {
      td.style.backgroundColor = 'rgba(255,255,255,0.1)';
    }
  }

  const exampleContainerMouseupCallback = (event) => {
    const hot = hotRef.current?.hotInstance;

    if (event.target.nodeName == 'INPUT' && event.target.className == 'checker') {
      isChecked = !event.target.checked;
      hot?.render();
    }
  };

  return (
    <div id="exampleContainer5" onMouseUp={(...args) => exampleContainerMouseupCallback(...args)}>
      <HotTable
        ref={hotRef}
        height="auto"
        columns={[{}, { renderer: customRenderer }]}
        colHeaders={function (col) {
          switch (col) {
            case 0:
              return '<b>Bold</b> and <em>Beautiful</em>';
            case 1:
              return `Some <input type="checkbox" class="checker" ${isChecked ? `checked="checked"` : ''}> checkbox`;
            default:
              return '';
          }
        }}
        autoWrapRow={true}
        autoWrapCol={true}
        licenseKey="non-commercial-and-evaluation"
      />
    </div>
  );
};

export default ExampleComponent;

TypeScript

import { useRef, MouseEvent } from 'react';
import Handsontable from 'handsontable/base';
import { HotTable, HotTableRef } from '@handsontable/react-wrapper';
import { registerAllModules } from 'handsontable/registry';
import { textRenderer } from 'handsontable/renderers/textRenderer';

// register Handsontable's modules
registerAllModules();

const ExampleComponent = () => {
  const hotRef = useRef<HotTableRef>(null);

  let isChecked = false;

  function customRenderer(this: Handsontable, _instance: Handsontable, td: HTMLTableCellElement) {
    textRenderer.apply(this, arguments as any);

    if (isChecked) {
      td.style.backgroundColor = 'yellow';
    } else {
      td.style.backgroundColor = 'rgba(255,255,255,0.1)';
    }
  }

  const exampleContainerMouseupCallback = (event: MouseEvent) => {
    const hot = hotRef.current?.hotInstance;

    if (
      (event.target as HTMLInputElement).nodeName == 'INPUT' &&
      (event.target as HTMLInputElement).className == 'checker'
    ) {
      isChecked = !(event.target as HTMLInputElement).checked;
      hot?.render();
    }
  };

  return (
    <div id="exampleContainer5" onMouseUp={(...args) => exampleContainerMouseupCallback(...args)}>
      <HotTable
        ref={hotRef}
        height="auto"
        columns={[{}, { renderer: customRenderer }]}
        colHeaders={function (col: number) {
          switch (col) {
            case 0:
              return '<b>Bold</b> and <em>Beautiful</em>';

            case 1:
              return `Some <input type="checkbox" class="checker" ${isChecked ? `checked="checked"` : ''}> checkbox`;

            default:
              return '';
          }
        }}
        autoWrapRow={true}
        autoWrapCol={true}
        licenseKey="non-commercial-and-evaluation"
      />
    </div>
  );
};

export default ExampleComponent;

Add event listeners in cell renderer function

If you are writing an advanced cell renderer, and you want to add some custom behavior after a certain user action (i.e. after user hover a mouse pointer over a cell) you might be tempted to add an event listener directly to table cell node passed as an argument to the renderer function. Unfortunately, this will almost always cause you trouble and you will end up with either performance issues or having the listeners attached to the wrong cell.

This is because Handsontable:

• Calls renderer functions multiple times per cell - this can lead to having multiple copies of the same event listener attached to a cell
• Reuses table cell nodes during table scrolling and adding/removing new rows/columns - this can lead to having event listeners attached to the wrong cell

Before deciding to attach an event listener in cell renderer make sure, that there is no Handsontable event that suits your needs. Using Handsontable events system is the safest way to respond to user actions.

If you did’t find a suitable Handsontable event put the cell content into a wrapping <div>, attach the event listener to the wrapper and then put it into the table cell.

Performance considerations

Cell renderers are called separately for every displayed cell, during every table render. Table can be rendered multiple times during its lifetime (after table scroll, after table sorting, after cell edit etc.), therefore you should keep your renderer functions as simple and fast as possible or you might experience a performance drop, especially when dealing with large sets of data.

If you only need to format the displayed value (e.g., add units, format dates, or apply text transformations), consider using the valueFormatter option instead of a custom renderer. The valueFormatter is called before the renderer and focuses solely on value transformation, making it more performant for simple formatting tasks. Use a renderer when you need to modify the DOM structure, add custom HTML elements, or handle complex visual layouts.

Related articles

APIs

BasePlugin→

Configuration options

renderer→

valueFormatter→

sanitizer→

Core methods

getCellMeta()→

getCellMetaAtRow()→

getCellsMeta()→

getCellRenderer()→

setCellMeta()→

setCellMetaObject()→

removeCellMeta()→

Hooks

afterGetCellMeta→

afterGetColumnHeaderRenderers→

afterGetRowHeaderRenderers→

afterRenderer→

beforeGetCellMeta→

beforeRenderer→