For up-to-date Handsontable documentation, see handsontable.com/docs.

Adapting Handsontable may be challenging, especially if your spreadsheet looks more like a fully-featured application, and not a typical spreadsheet. Although Handsontable comes with six pre-built cell renderers, they won’t address the needs of developers in all scenarios, particularly when it comes to complex applications. This is why Handsontable also supports the creation of custom renderers, separate from the extendibility of the pre-built renderers, addressing almost any custom grid functionality needed by developers.

One of the key elements extending Handsontable’s capabilities is the cell. Its structure consists of just three elements:

• Editor
• Renderer
• Validator

Depending on how a particular cell or range of cells should behave, these three functions can be defined separately or together. It might be confusing in the beginning, so in this article, I will focus mainly on how to apply different types of renderers into your grid.

What is a cell renderer

Handsontable displays the values stored in the data source indirectly. This means that every time a value from a data source needs to be displayed in a table cell, it is passed to the cell renderer function, together with the table cell object type HTMLTableCellElement.

The cell renderer is expected to format the passed value and place it as the content of the cell object. Renderers can also alter the CSS class, i.e. to let the user know that the displayed value is invalid.

Native cell renderers

Handsontable has 6 built-in renderers which can be used out of the box, or extended when necessary. They are well-documented, but let me recap them briefly below:

textRenderer

This is the default cell renderer which allows users to type in anything as plain text, and it does not trigger any validator.

The first example below is pretty simple. It just loads a few basic pieces of information about different type of plants:

autocompleteRenderer

This popular option renders an autocomplete field which allows users to quickly find and pick values from the pre-defined list.

The goal of the following demo is to mark one of the fields red if certain conditions have been met. In this case if you choose an Age above 50, it will turn red, otherwise it remains green. Under the hood I just used a cells method to determine values and added the relevant CSS class to the cell.

checkboxRenderer

This renderer allows users to display a checkbox in a cell. It can be set as a boolean type or any other type, depending on your configuration.

Here you can see how to change the background color depending on the current checkbox value:

htmlRenderer

This renderer enables users to place HTML code inside a cell. Note that this renderer does not prevent any XSS attacks by default, so be sure to add adequate security measures to your app.

In the following demo I placed HTML code in each column, displaying information about the most notable contributors to popular GitHub projects.

numericRenderer

This renderer allows users to properly display different formats of numbers. It also handles our date and time cells.

In the demo below I display the same value in the various decimal formats typical for France, US and Spain. The last two columns contain date and time values.

passwordRenderer

This allows users to display masked characters. By default it uses asterisks, but this can easily be replaced with custom characters, like circles. The data is saved and stored as plain text.

All the rendered passwords always have the same length for security purposes, though the edited values have the correct length. In the example below I present you three different scenarios:

• Default configuration showing a fixed length of the rendered password
• The rendered length of the masked value is the same as the length of the actual password
• The edited value is displayed as a plain, unmasked value

Custom cell renderers

The true beauty of Handsontable as a framework is in its flexibility, and the fact that it doesn’t want to confine users in any way. I won’t be digging deep into the technical details, as by studying the code below you’ll be able to check which API methods we used to create the example:

For more information about the technical details you can visit custom renderers tutorial.

Skeleton

Instead of building your custom renderer from scratch you can lean on the Skeleton prepared by the Handsontable Team to cut your development time. You can find it on GitHub.

Performance matters

It is easy to forget about performance issues with Handsontable handling most of the work for you. However, it must be stated that filling your spreadsheet with custom renderers will inevitably affect your grid’s performance. For a grid of 100 columns and rows, you are basically triggering 10 000 additional functions. Luckily, there are several ways to optimize the performance of renderers, which I will outline in another blog post.

Conclusion

At first glance, spreadsheets may look like a simple set of different sized rectangles. And while they seem to be very uncomplicated, the ‘logic’ beneath them may be very complex and advanced. In this article I have shown how easy it is to modify a cell’s body by using predefined options, as well as by creating more sophisticated constructions relying on the Handsontable API.