Skip to content

Radio buttons

This tutorial shows you how to build a custom radio button cell type using a renderer that displays radio inputs directly in cells, with ARIA semantics, roving tabindex, and keyboard navigation.

TypeScript
/* file: app.component.ts */
import { Component } from '@angular/core';
import { GridSettings, HotTableModule } from '@handsontable/angular-wrapper';
import { rendererFactory } from 'handsontable/renderers';
import { BaseEditor } from 'handsontable/editors/baseEditor';
import { registerCellType } from 'handsontable/cellTypes';
import type { CellProperties } from 'handsontable/settings';
import type Handsontable from 'handsontable/base';
/* start:skip-in-preview */
const inputData = [
{ task: 'Refactor licensing app navigation', priority: 'high', status: 'in-progress' },
{ task: 'Theme Builder onboarding tour', priority: 'medium', status: 'todo' },
{ task: 'MCP server v1 release prep', priority: 'high', status: 'in-progress' },
{ task: 'GitHub triage rotation docs', priority: 'low', status: 'done' },
{ task: 'shadcn/ui integration recipe', priority: 'medium', status: 'todo' },
];
/* end:skip-in-preview */
type RadioOption = { value: string; label: string } | string;
interface RadioCellProperties extends CellProperties {
options: RadioOption[];
}
class RadioEditor extends BaseEditor {
override init(): void {}
override open(): void {}
override close(): void {}
override focus(): void {}
override getValue(): string { return this.originalValue as string; }
override setValue(value: string): void { this.originalValue = value; }
}
const radioRenderer = rendererFactory(({ instance, td, row, column, value, cellProperties }) => {
while (td.firstChild) td.removeChild(td.firstChild);
const options: RadioOption[] = (cellProperties as RadioCellProperties).options || [];
const wrapper = document.createElement('div');
wrapper.className = 'htRadioCell';
wrapper.setAttribute('role', 'radiogroup');
const colHeader = instance.getColHeader(column as number);
if (colHeader) wrapper.setAttribute('aria-label', String(colHeader));
// A cell with no editor cannot be changed by the user, so its radios are disabled the same
// way `readOnly` disables them. `editor: false` set at any configuration level reaches the
// cell through the cascade. Read the option directly: `getCellEditor()` throws on an editor
// name that isn't registered, and a renderer runs on every draw.
const isEditable = !cellProperties.readOnly &&
cellProperties.editor !== false && cellProperties.editor !== null;
const hasChecked = options.some((opt) => {
const v = typeof opt === 'object' ? opt.value : opt;
return String(v) === String(value);
});
const cycle = (direction: 'next' | 'prev') => {
if (!options.length) return;
const i = options.findIndex((opt) => {
const v = typeof opt === 'object' ? opt.value : opt;
return String(v) === String(value);
});
const last = options.length - 1;
const next = direction === 'next'
? (i === last || i === -1 ? 0 : i + 1)
: (i <= 0 ? last : i - 1);
const newValue = typeof options[next] === 'object'
? (options[next] as { value: string }).value
: (options[next] as string);
instance.setDataAtCell(row as number, column as number, newValue);
queueMicrotask(() => {
const newTd = instance.getCell(row as number, column as number);
newTd?.querySelector<HTMLInputElement>(`input[type="radio"][value="${CSS.escape(newValue)}"]`)?.focus();
});
};
options.forEach((opt, idx) => {
const optValue = typeof opt === 'object' ? opt.value : opt;
const optLabel = typeof opt === 'object' ? opt.label : opt;
const label = document.createElement('label');
label.className = 'htUIRadio';
const input = document.createElement('input');
input.type = 'radio';
input.className = 'htUIRadioInput';
input.name = `radio-r${row}-c${column}`;
input.value = optValue;
input.checked = String(optValue) === String(value);
input.tabIndex = (input.checked || (!hasChecked && idx === 0)) ? 0 : -1;
input.disabled = !isEditable;
const span = document.createElement('span');
span.className = 'htUIRadioLabel';
span.textContent = optLabel;
// The checked dot is a real `<i class="ht-icon ht-icon-radio">` element (Handsontable
// itself inserts one as the input's next sibling for its own radio UI), not a CSS
// pseudo-element -- so the recipe must add it explicitly to get the dot.
const icon = document.createElement('i');
icon.className = 'ht-icon ht-icon-radio';
icon.setAttribute('aria-hidden', 'true');
label.appendChild(input);
label.appendChild(icon);
label.appendChild(span);
wrapper.appendChild(label);
input.addEventListener('change', (e) => {
e.stopPropagation();
const v = (e.target as HTMLInputElement).value;
instance.setDataAtCell(row as number, column as number, v);
queueMicrotask(() => {
const newTd = instance.getCell(row as number, column as number);
newTd?.querySelector<HTMLInputElement>(`input[type="radio"][value="${CSS.escape(v)}"]`)?.focus();
});
});
// Stop mousedown so Handsontable doesn't hijack the click for cell selection - but only
// while the radios are interactive. On a non-editable cell the click would otherwise do
// nothing at all, leaving no way to select the cell by clicking it.
label.addEventListener('mousedown', (e) => {
if (isEditable) {
e.stopPropagation();
}
});
input.addEventListener('keydown', (e) => {
if (e.key === 'Escape') {
e.preventDefault();
e.stopPropagation();
instance.selectCell(row as number, column as number);
return;
}
if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
e.preventDefault();
e.stopPropagation();
cycle('next');
return;
}
if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
e.preventDefault();
e.stopPropagation();
cycle('prev');
return;
}
e.stopPropagation();
});
});
td.appendChild(wrapper);
td.style.verticalAlign = 'top';
});
// eslint-disable-next-line @typescript-eslint/no-explicit-any
registerCellType('radio', { editor: RadioEditor, renderer: radioRenderer } as any);
const priorityOptions: RadioOption[] = [
{ value: 'low', label: 'Low' },
{ value: 'medium', label: 'Medium' },
{ value: 'high', label: 'High' },
];
const statusOptions: RadioOption[] = [
{ value: 'todo', label: 'Todo' },
{ value: 'in-progress', label: 'In progress' },
{ value: 'done', label: 'Done' },
];
@Component({
standalone: true,
imports: [HotTableModule],
selector: 'example1-radio',
template: `<div><hot-table [data]="data" [settings]="gridSettings"></hot-table></div>`,
})
export class AppComponent {
readonly data = inputData;
readonly gridSettings: GridSettings = {
colHeaders: ['Task', 'Priority', 'Status'],
rowHeaders: true,
height: 'auto',
width: '100%',
minRowHeights: 96,
columns: [
{ data: 'task', type: 'text', width: 300 },
{ data: 'priority', type: 'radio', width: 160, options: priorityOptions } as Handsontable.ColumnSettings,
{ data: 'status', type: 'radio', width: 170, options: statusOptions } as Handsontable.ColumnSettings,
],
afterInit(this: Handsontable.Core) {
this.rootElement.addEventListener('keydown', (e) => {
if ((e.target as HTMLElement).tagName === 'INPUT') return;
if (e.key !== 'Enter' && e.key !== 'F2') return;
const sel = this.getSelectedLast();
if (!sel) return;
const [r, c] = sel;
if (this.getCellMeta(r, c)['type'] !== 'radio') return;
const td = this.getCell(r, c);
const target = td?.querySelector<HTMLInputElement>('input[type="radio"]:checked')
?? td?.querySelector<HTMLInputElement>('input[type="radio"]');
if (target) {
e.stopImmediatePropagation();
e.preventDefault();
target.focus();
}
}, true);
},
};
}
/* end-file */
/* file: app.config.ts */
import { ApplicationConfig, provideZoneChangeDetection } from '@angular/core';
import { registerAllModules } from 'handsontable/registry';
import { HOT_GLOBAL_CONFIG, HotGlobalConfig } from '@handsontable/angular-wrapper';
registerAllModules();
export const appConfig: ApplicationConfig = {
providers: [
provideZoneChangeDetection({ eventCoalescing: true }),
{
provide: HOT_GLOBAL_CONFIG,
useValue: {
// license: 'your-license-key', // get a key at https://handsontable.com/pricing/
} as HotGlobalConfig,
},
],
};
/* end-file */
HTML
<div>
<example1-radio></example1-radio>
</div>
CSS
/* Scoped to .htRadioCell so theme's .htUIRadio styles in context menus and
filter panels are not affected. The ring, colors, and checked state are
intentionally left to the Handsontable theme; the checked dot is a
`.ht-icon-radio` element the renderer inserts as the input's next sibling
(see Step 4 in the guide), not something this stylesheet draws. */
.htRadioCell {
display: flex;
flex-direction: column;
gap: 2px;
padding: 4px 0;
line-height: 1.4;
}
.htRadioCell .htUIRadio {
display: inline-flex;
align-items: center;
gap: 8px;
font-size: 13px;
color: var(--ht-foreground-color, #1f2937);
padding: 2px 6px !important;
border-radius: 4px;
cursor: pointer;
user-select: none;
}
.htRadioCell .htUIRadioLabel {
flex: 1;
}
/* Ensure pointer cursor and prevent default outline; theme handles appearance. */
.htRadioCell .htUIRadio > input[type='radio'] {
cursor: pointer;
}

Overview

This guide shows how to build a renderer-based radio cell type. The radio buttons are always visible inside the cell — no editor popup. The approach is identical to the JavaScript version: rendererFactory builds the radio UI, a BaseEditor stub satisfies the cell-type API, and an afterInit hook adds the Enter/F2 bridge.

Difficulty: Intermediate Time: ~20 minutes Libraries: None (pure HTML and CSS)

What You’ll Build

A cell type that:

  • Renders a list of labeled radio buttons directly in the cell (always visible, no editor popup)
  • Stores a single selected value per cell
  • Accepts an options array ({ value, label } or plain strings) per column
  • Supports keyboard navigation (ArrowDown, ArrowUp, Escape)
  • Uses roving tabindex for correct Tab behavior within the group
  • Exposes role="radiogroup" with a label derived from the column header
  • Works without any external libraries

Prerequisites

None. This uses only native HTML, CSS, and the Handsontable DataGrid API.

  1. Import Dependencies

    app.component.ts
    import { Component } from '@angular/core';
    import { GridSettings, HotTableModule } from '@handsontable/angular-wrapper';
    import { rendererFactory } from 'handsontable/renderers';
    import { BaseEditor } from 'handsontable/editors/baseEditor';
    import { registerCellType } from 'handsontable/cellTypes';
    // app.config.ts — registerAllModules() is called here
    import { registerAllModules } from 'handsontable/registry';
    registerAllModules();
  2. Add CSS Styling

    Create a separate CSS file. All styles are scoped to .htRadioCell so they do not affect the same .htUIRadio classes used by context menus and filter panels.

    .htRadioCell {
    display: flex;
    flex-direction: column;
    gap: 2px;
    padding: 4px 0;
    line-height: 1.4;
    }
    .htRadioCell .htUIRadio {
    display: inline-flex;
    align-items: center;
    gap: 8px;
    font-size: 13px;
    color: var(--ht-foreground-color, #1f2937);
    padding: 2px 6px !important;
    border-radius: 4px;
    cursor: pointer;
    user-select: none;
    }
    .htRadioCell .htUIRadioLabel {
    flex: 1;
    }
    .htRadioCell .htUIRadio > input[type='radio'] {
    cursor: pointer;
    }

    Handsontable token used:

    • --ht-foreground-color — label text color

    Why only layout CSS?

    The Handsontable theme already handles the radio indicator’s ring, colors, and states through .htUIRadio > input[type="radio"], using its own --ht-radio-* CSS variables. The checked dot itself is a separate <i class="ht-icon ht-icon-radio"> element, styled by the theme through input[type="radio"] + .ht-icon. The renderer in Step 4 creates that element as the input’s next sibling, so the recipe gets the dot for free without any extra CSS. The CSS file here only provides the container layout (vertical flex, padding, row alignment) without overriding those built-in indicator styles.

  3. Editor Stub

    Angular uses the same BaseEditor stub as JavaScript. The renderer handles all interaction.

    class RadioEditor extends BaseEditor {
    init(): void {}
    open(): void {}
    close(): void {}
    focus(): void {}
    getValue(): string { return this.originalValue as string; }
    setValue(value: string): void { this.originalValue = value; }
    }
  4. Renderer — Build the Radio UI

    The renderer builds the radio group on every render. It empties the cell, then creates one <label class="htUIRadio"> row per option.

    const radioRenderer = rendererFactory(({ instance, td, row, column, value, cellProperties }) => {
    while (td.firstChild) td.removeChild(td.firstChild);
    const options = (cellProperties as RadioCellProperties).options || [];
    const wrapper = document.createElement('div');
    wrapper.className = 'htRadioCell';
    wrapper.setAttribute('role', 'radiogroup');
    // ARIA label from the column header
    const colHeader = instance.getColHeader(column as number);
    if (colHeader) wrapper.setAttribute('aria-label', String(colHeader));
    // ... build options, attach listeners, append to td
    td.appendChild(wrapper);
    td.style.verticalAlign = 'top';
    });

    What’s happening:

    • rendererFactory passes the full renderer context: instance, td, row, column, value, cellProperties.
    • cellProperties.options carries the per-column option list.
    • role="radiogroup" + aria-label make the group announce correctly to screen readers.
    • Each option inserts an <i class="ht-icon ht-icon-radio"> element as the input’s next sibling — that’s what paints the checked dot; see Step 2.
    • td.style.verticalAlign = 'top' aligns the stacked options to the top of the cell.
  5. Roving Tabindex

    Only one radio per group should be reachable with Tab. The checked option (or the first option when nothing is selected) gets tabIndex=0; all others get -1.

    const hasChecked = options.some((opt) => {
    const v = typeof opt === 'object' ? opt.value : opt;
    return String(v) === String(value);
    });
    options.forEach((opt, idx) => {
    const optValue = typeof opt === 'object' ? opt.value : opt;
    const input = document.createElement('input');
    input.checked = String(optValue) === String(value);
    input.tabIndex = (input.checked || (!hasChecked && idx === 0)) ? 0 : -1;
    // ...
    });

    Why roving tabindex?

    The ARIA Authoring Practices Guide for radio groups requires exactly one tabbable element in the group. This lets keyboard users Tab past a whole column of radio cells, then use arrow keys to navigate within a cell they care about.

  6. Click and Change Handlers

    Clicking a radio saves the value to the data model and restores focus after Handsontable re-renders the cell.

    input.addEventListener('change', (e) => {
    e.stopPropagation();
    const v = (e.target as HTMLInputElement).value;
    instance.setDataAtCell(row as number, column as number, v);
    queueMicrotask(() => {
    const newTd = instance.getCell(row as number, column as number);
    newTd?.querySelector<HTMLInputElement>(`input[type="radio"][value="${CSS.escape(v)}"]`)?.focus();
    });
    });
    // Stop mousedown so Handsontable doesn't steal the click for cell selection.
    label.addEventListener('mousedown', (e) => e.stopPropagation());

    Why queueMicrotask?

    setDataAtCell triggers a synchronous re-render that replaces the DOM. The focused element disappears. queueMicrotask schedules a microtask that runs after the render, finds the new radio by value, and refocuses it — without a visible flicker.

    Why stop mousedown?

    Handsontable listens for mousedown on the table to update cell selection. Without stopPropagation, clicking a radio also repositions the Handsontable cursor, which can interfere with focus management.

  7. Keyboard Navigation

    Each radio listens for arrow keys and Escape.

    input.addEventListener('keydown', (e) => {
    if (e.key === 'Escape') {
    e.preventDefault();
    e.stopPropagation();
    instance.selectCell(row as number, column as number); // return focus to grid
    return;
    }
    if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
    e.preventDefault();
    e.stopPropagation();
    cycle('next');
    return;
    }
    if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
    e.preventDefault();
    e.stopPropagation();
    cycle('prev');
    return;
    }
    // Block remaining keys from Handsontable's shortcut system.
    e.stopPropagation();
    });

    The cycle helper finds the current index, computes next/prev with wrap-around, calls setDataAtCell, and schedules a queueMicrotask focus restore — the same pattern as the click handler.

  8. Enter / F2 Bridge

    In Angular, the listener goes inside the afterInit hook in gridSettings — the hook receives this as the Handsontable instance:

    readonly gridSettings: GridSettings = {
    // ...
    afterInit(this: Handsontable.Core) {
    this.rootElement.addEventListener('keydown', (e) => {
    if ((e.target as HTMLElement).tagName === 'INPUT') return;
    if (e.key !== 'Enter' && e.key !== 'F2') return;
    const sel = this.getSelectedLast();
    if (!sel) return;
    const [r, c] = sel;
    if (this.getCellMeta(r, c).type !== 'radio') return;
    const td = this.getCell(r, c);
    const target = td?.querySelector<HTMLInputElement>('input[type="radio"]:checked')
    ?? td?.querySelector<HTMLInputElement>('input[type="radio"]');
    if (target) { e.stopImmediatePropagation(); e.preventDefault(); target.focus(); }
    }, true);
    },
    };
  9. Register and Use in Handsontable DataGrid

    Register the cell type and use type: 'radio' in the column config. Add the Enter/F2 bridge via afterInit:

    registerCellType('radio', { editor: RadioEditor, renderer: radioRenderer });
    readonly gridSettings: GridSettings = {
    minRowHeights: 96,
    columns: [
    { data: 'task', type: 'text' },
    { data: 'priority', type: 'radio', options: priorityOptions },
    { data: 'status', type: 'radio', options: statusOptions },
    ],
    afterInit(this: Handsontable.Core) {
    this.rootElement.addEventListener('keydown', (e) => {
    // ... same Enter/F2 bridge as JavaScript
    }, true);
    },
    };

    Why minRowHeights: 96?

    The default row height (~28 px) is too short to display three stacked options with padding. Setting a minimum height ensures the radio group fits without overflowing, and the row still grows if the options need more room.

How It Works - Complete Flow

  1. Render: Handsontable calls radioRenderer for each radio cell. The renderer empties the cell and builds the <label> / <input type="radio"> group from cellProperties.options.
  2. View: Radio buttons are always visible. The checked option reflects the current cell value.
  3. Click: The change event fires, calls setDataAtCell, and queues a microtask to refocus the now-rebuilt radio.
  4. Arrow keys: Each radio’s keydown listener calls cycle(), which calls setDataAtCell and queues a focus restore.
  5. Enter / F2: The capture-phase listener on rootElement catches the key before Handsontable, then focuses the checked (or first) radio.
  6. Escape: The radio’s keydown listener calls instance.selectCell() to return focus to the grid cursor.

Enhancements

  1. Allow Per-Cell Options

    Override options from cellProperties at the cell level using Handsontable’s cells callback:

    cells(row, col) {
    if (col === 1 && row === 2) {
    return { options: [{ value: 'critical', label: 'Critical' }] };
    }
    }
  2. Read-Only State

    Mark individual cells as non-interactive by setting readOnly: true in the column or via cells():

    columns: [
    { data: 'status', type: 'radio', options: statusOptions, readOnly: true },
    ]

    The renderer checks cellProperties.readOnly and sets disabled on all radio inputs, which blocks both click changes and keyboard navigation. Handsontable also dims the cell background automatically.

  3. Validator for Allowed Values

    Reject values not present in the options list:

    const radioValidator = (value, callback) => {
    callback(priorityOptions.some((o) => o.value === value));
    };
    columns: [
    { data: 'priority', type: 'radio', options: priorityOptions, validator: radioValidator },
    ]

Accessibility

Keyboard navigation:

  • Tab: Move to the next tabbable radio group (one per cell, via roving tabindex).
  • Enter / F2: Enter the radio group from the grid cursor.
  • ArrowDown / ArrowRight: Move to the next option (wraps).
  • ArrowUp / ArrowLeft: Move to the previous option (wraps).
  • Escape: Return focus to the grid.

Screen reader support:

  • role="radiogroup" on the wrapper.
  • aria-label derived from the column header.
  • Each option is a native <input type="radio"> with a visible <label>.

What you learned

You built a renderer-based radio cell type using Handsontable’s rendererFactory and a minimal BaseEditor stub. You learned the roving tabindex pattern, the queueMicrotask focus-restore technique, and how to intercept Enter/F2 in capture phase to bridge keyboard navigation between the grid cursor and the radio group.

Next steps

  • Feedback - Another custom cell type using editorFactory and an editor popup.
  • Star Rating - SVG-based custom renderer using rendererFactory.
  • Custom cell type - The full reference for renderer, editor, and validator registration.