Tutorial: Custom renderers

Custom renderers

Registering a renderer

When you create a renderer, a good idea is to assign it as an alias that will refer to this particular renderer function. Handsontable defines 10 aliases by default:

  • autocomplete for Handsontable.renderers.AutocompleteRenderer
  • base for Handsontable.renderers.BaseRenderer
  • checkbox for Handsontable.renderers.CheckboxRenderer
  • date for Handsontable.renderers.DateRenderer
  • dropdown for Handsontable.renderers.DropdownRenderer
  • html for Handsontable.renderers.HtmlRenderer
  • numeric for Handsontable.renderers.NumericRenderer
  • password for Handsontable.renderers.PasswordRenderer
  • text for Handsontable.renderers.TextRenderer
  • time for Handsontable.renderers.TimeRenderer

It gives users a convenient way for defining which renderer should be used when table rendering was triggered. User doesn't need to know which renderer function is responsible for displaying the cell value, he does not even need to know that there is any function at all. What is more, you can change the render function associated with an alias without a need to change code that defines a table.

To register your own alias use Handsontable.renderers.registerRenderer() function. 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 asterixDecoratorRenderer under alias asterix you have to call:

Handsontable.renderers.registerRenderer('asterix', asterixDecoratorRenderer);

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

Handsontable.renderers.registerRenderer('text', asterixDecoratorRenderer);

// Now 'text' alias points to `asterixDecoratorRenderer` function, not Handsontable.renderers.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.

Handsontable.renderers.registerRenderer('asterix', asterixDecoratorRenderer);

// Someone might already registered such alias

Handsontable.renderers.registerRenderer('my.asterix', asterixDecoratorRenderer); // That's better.

Using an alias

The final touch is to using the registered aliases, so that users can easily refer to it without the need to now the actual renderer function is.

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

(function(Handsontable){
  function customRenderer(hotInstance, td, row, column, prop, value, cellProperties) {
    // Optionally include `BaseRenderer` which is responsible for adding/removing CSS classes to/from the table cells.
    Handsontable.renderers.BaseRenderer.apply(this, arguments);

    // ...your custom logic of the renderer
  }

  // Register an alias
  Handsontable.renderers.registerRenderer('my.custom', customRenderer);

})(Handsontable);

From now on, you can use customRenderer like so:

var hot = new Handsontable(document.getElementById('container'), {
  data: someData,
  columns: [
    {
      renderer: 'my.custom'
    }
  ]
}); 

Rendering 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:

  • 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

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.

Help us improve this page