Installation

kob-ui ships one JavaScript file and one stylesheet. There is nothing to install alongside it and no build step unless you want one.

Upgrading

Already installed? Upgrade with npm i kob-ui@latest. npm update will not do it: npm saves the package as ^0.x.y, and while the version starts 0. that range only accepts patch releases, so a new minor with new widgets is never picked up. What is new in each release is in the changelog that ships in the package, node_modules/kob-ui/CHANGELOG.md.

Script tag

Bundler

What is in the package

Creating widgets

Every widget has one accessor. Call it with options to build the widget; call it again with nothing to get the same instance back.

Methods return the instance where there is nothing else to return, so they chain: grid.search('bangkok').gotoPage(1).

Events

Callbacks are options, named onSomething. Inside one, this is the widget's element.

Cleanup

destroy() unbinds listeners and puts the DOM back roughly as it was. Kob.unparse(root) does it for everything under an element — worth calling before you tear a screen out of the page.

Markup and data-options

A widget can also be declared in HTML. Kob.parse(root) walks the markup and builds anything whose class names a widget.

Parsing twice is safe: an element that already carries a widget is skipped, so you can call it again after injecting HTML.

What data-options accepts

Quoted strings, numbers, true, false and null. Functions, formatters and column arrays have no sensible text form, so pass those from JavaScript.

Loading remote data

combobox and datagrid both take a url. Everything they fetch goes through one function, so authentication and response shapes are configured once for the whole library.

A single widget can still reshape its own payload with loadFilter.

Theming

Nothing in the stylesheet hard-codes a colour. Redefine the tokens on :root — or on any container — and everything inside follows.

Scrollbars

The browser's own scrollbars are a fixed grey that reads as a foreign object on a dark surface, so every box the library scrolls gets one painted from the tokens instead — vertical, horizontal, and the corner where the two meet. Anything scrolling inside a window, panel or layout matches too.

To carry the same treatment to the rest of the page, put the class on the root element:

A region that keeps its own colours — a dark code panel on a light page, say — just redefines the tokens locally:

The five themes

Five palettes ship. Leave the attribute off and the library follows the operating system, choosing between light and dark; set it and that choice is pinned.

Switching at runtime is one attribute. Remembering the choice is on you — the library never writes to storage:

A theme of your own is one more block. Only the tokens that differ need redefining — everything else falls through to the light values:

Localisation

Every string the widgets show, plus the date format and calendar era, comes from the active locale. English and Thai are built in.

The datebox example further down switches between English and Thai live, and reports both what is on screen and what getValue() returns.

Icons

181 single-colour SVGs applied as a CSS mask. They take the element's color, live inside the stylesheet, and cost no requests.

The full set — click any icon to copy its class name:

Your own artwork works the same way, without touching the library — point the mask at your SVG:

textbox, numberbox, passwordbox

Three thin wrappers over <input>: an optional label, a required flag, and for numbers, clamping and formatting.

Options

Methods

textbox: masks, addons and counters

The furniture a plain input grows once it is in a real form: a shape the typing has to take, a currency in front of it, a count underneath.

The mask types its own literals. Somebody entering a phone number types ten digits and the dashes appear; making them type the dash is how a masked field ends up slower than an unmasked one. A value pasted with its own punctuation is reshaped to the mask, and a half-typed value does not grow a trailing separator.

getValue() returns the masked text — what the user sees, what they would copy, and what a validation message has to be about. getRaw() is the characters underneath, for the API call that wants 0812345678.

combobox

A text input backed by a list. The value the form submits and the text the user reads are kept apart, so an id column never leaks onto screen.

Read-only. readonly: true (or .readonly(true)) is understood by combobox, datebox, datetimebox, monthbox, yearbox, timebox, tagbox, colorpicker, combogrid and combotree: the value is shown and can be selected and copied, the list or calendar will not open, and chips cannot be removed. It sets aria-readonly. disabled given as an option is applied the same way. checkbox, radiobox, slider, filebox and daterangebox take the same option.

Options

Methods

Keyboard: arrows move through the list, Enter picks, Escape closes. The input is announced as a combobox and the list as a listbox, with the highlighted row named by aria-activedescendant.

Picking several

multiple: true turns the field into a list. The chosen rows become chips in front of the typing area, getValue() returns an array — and takes one, or a comma-separated string — clicking a row again takes it off, and Backspace in an empty box removes the last chip, which is the gesture every tag field has.

combobox: searching, grouping, and adding

Three options that decide whether a combobox can be pointed at a table of forty thousand rows or only at a list of twelve.

A remote field loads nothing on the way up and does not filter what comes back: the server already answered the question, and filtering its answer again would hide rows it matched for reasons of its own — a customer found by phone number, an item found by barcode. Answers to questions that are no longer the current one are dropped, because three keystrokes are three requests and the slowest must not win.

For a lookup that needs more than one line per row, see combogrid; for one out of a hierarchy, see combotree.

datebox

A text field with a month calendar. It reads and writes ISO dates whatever the locale displays.

Options

Methods

monthbox and yearbox

A period rather than a day. A payroll run, a VAT return, a sales report, a meter reading: the answer is "March 2026", and a datebox would make somebody pick a day that is then ignored. getValue() is 'yyyy-mm' — or 'yyyy' for yearbox — in the Gregorian calendar, whatever the locale shows.

Options

Methods

checkbox

A real <input type="checkbox"> drawn as a switch, so forms submit it and getValue() is simply its checked state.

Methods: getValue(), setValue(v), check(), uncheck(), toggle(), enable(), disable().

searchbox

A text input that looks and behaves like a search field: a magnifier on the left, a clear button that appears once there is something to clear, Escape to empty it, and onSearch debounced so holding a key down costs one search rather than twenty.

It inherits label, labelWidth, prompt and the rest from textbox. Methods: getValue() (trimmed), setValue(), clear(), search(value?) — which runs onSearch immediately, ignoring both the debounce and the guard that skips an unchanged query.

filebox

A drop zone and a file list. Drag files onto it or click to browse; it checks them against accept, maxSize and maxFiles, lists what survived, and — if you give it a url — uploads each one with a progress bar.

Methods: add(files), remove(index), clear(), getFiles(), getItems() (each with its status and percent), upload(), enable() / disable().

Uploads go through XMLHttpRequest rather than fetch, because fetch still cannot report upload progress — and the progress bar is most of the point of a file field. One request per file, so a single failure does not lose the batch.

linkbutton

Turns an <a> or <button> into a toolbar button with an icon.

Colours

Five colours, in two weights. Solid is for the one action a screen is really about — Save, Delete. Soft is the same meaning at a fraction of the weight, for the row of secondary actions beside it, so a toolbar of six buttons does not end up shouting six things at once.

Add soft: true or kob-linkbutton-soft for the tonal version. The same five work on a plain <button class="kob-btn kob-btn-danger"> with no JavaScript at all.

Methods: setText(s), getText(), setIcon(cls), toggle(on?), isSelected(), enable(), disable().

Icon and caption

iconAlign puts the icon on any of the four sides. 'left' and 'right' are the shapes a form wants; 'top' and 'bottom' stack the two into a column, which is the button a desktop toolbar has been made of for thirty years — a large glyph, its name underneath. A caption too long for the column wraps under the glyph rather than stretching the strip sideways.

size takes 'sm' and 'lg', with the middle size as the default. Stacked and large together is the toolbar shape, and there the extra size goes into the glyph rather than the label: a toolbar button is found by its picture and confirmed by its name.

A toolbar

There is no toolbar widget, and none is needed: the strip is kob-toolbar, a flex row with a gap, and two helpers — kob-sep draws a divider between groups of commands, kob-spacer pushes everything after it to the far end. What goes in it are ordinary buttons, so the behaviour every toolbar actually needs — Delete greyed out until something is selected — is enable() and disable() on the button itself.

form

Collects every kob-ui field inside a <form> so you can read, fill, validate and clear them in one call — whatever mix of widgets they are.

Loading a record, and saving it

Every record screen was writing the same four steps by hand: fetch, unwrap, fill, and remember to mark the form clean afterwards — that last one being what everybody forgets, which is how a form that has only been loaded ends up warning about unsaved changes.

Validation

required answers one question about a field. Everything else it has to satisfy — an address that looks like one, a code in a format, a quantity inside a bound, a password typed twice — is a rules option away, on every field widget there is.

Writing a rule

A rule is one of three things, and rules takes one or a list:

The named rules

Where the message comes from, and where it goes

Each named rule carries its own sentence, from the locale bundle, so Kob.locale('th') changes what a failing field says along with everything else. message on the field overrides whichever rule failed, which is what you want when a field has one rule and a better sentence to say about it.

The message is written under the whole field — under the label wrapper, not between the label and the input — and the control is given aria-invalid and an aria-describedby pointing at it. A red border says that something is wrong; it never says what.

When it runs

A field that has no rules behaves as it always did — marked when the form is submitted, not while it is being filled in — so nothing about an existing form changes until you give one a rule.

A rule of your own

radiobox

One choice out of several. The widget mounts on the box that holds the options rather than on an input, because a single radio button means nothing on its own — the group is what a form reads, validates and fills in.

Options

Methods: getValue(), setValue(v), setItems(items), clear(), enable(), disable(), isValid(), validationMessage().

timebox, datetimebox and daterangebox

The three fields a scheduling or reporting screen needs and a calendar alone cannot give it: a time of day, a timestamp, and a period with two ends that hold each other in order.

timebox

A list of times at a sensible step, because a free-text time field is a small disaster in a form somebody fills in fifty times a day — everyone writes it differently and someone has to parse it afterwards. Typing still works, and forgivingly: 9, 905, 9:05 pm, 21.5 and 2130 all mean something. What leaves through getValue() is always 'HH:mm' on a 24-hour clock.

Methods: getValue(), setValue(v), getText(), clear(), focus(), enable(), disable(), isValid().

datetimebox

The datebox calendar with a time strip under it, so the day and the time are one gesture and one field rather than two that have to be recombined and kept in step by hand. Every datebox option applies, plus step, hour12 and defaultTime — what a day picked with no time yet means.

daterangebox

From one date to another, as one field. It mounts on a box rather than an input, since two inputs go inside it, and it does the three things every application was writing by hand: it stops the end being earlier than the start — the calendars simply will not offer those days — it carries the shortcuts a reporting screen reaches for, and it hands the pair over as one value.

panel

A titled content box that can fold away or load its body from a URL — and parse the widgets in whatever comes back.

A panel with a title is a region named by it. The fold button carries aria-expanded and says "Fold this panel" or "Open this panel" in the current locale.

Methods: getBody(), setTitle(s), load(url), setContent(html), collapse(), expand(), toggleCollapse(), close().

layout

The classic five-region frame. Regions are declared on the children; the widget restacks them once so flexbox can do the sizing.

Keyboard: a splitter is a focusable role="separator". The arrow keys along its axis move it ten pixels (eighty with Shift), within minSize and maxSize, and Enter folds a collapsible region. The fold button carries aria-expanded.

Region options

Set these in each child's data-options.

Methods: panel(region) returns the region element, plus resize(region, px), collapse(region), expand(region), toggle(region), remove(region).

Events: onResize(region, size), onCollapse(region), onExpand(region).

tabs

Every direct child carrying a title attribute becomes a page.

Methods: select(i), selectByTitle(s), getSelected(), getPanel(i), getPages(), add({ title, content, iconCls, closable }), close(i).

Per-page options

A page carries its own settings in data-options, next to the title the tab is named after:

Three looks

The default is a folder: the selected tab is a raised card that overlaps the strip below it, so it and the page read as one surface. Two classes on the container change that without touching the markup inside.

stepper

The path through a multi-step task, across the page or down it. Give it children with a title and each one becomes a step and the panel shown while that step is current; give it none and it is the indicator on its own.

Methods: go(i), next(), prev(), finish(), reset(), canReach(i), isFirst(), isLast(), isFinished(), getActive(), getStep(i?), getSteps(), getPanel(i?), setStatus(i, status), error(i?), setSteps(list).

States

A step is done, active or todo according to where it sits relative to the current one. Pinning a status — on the step object or through setStatus() — overrides that, and is how a failed step stays red after the user has moved on:

dialog and modal

Built around an element that is already on the page: it keeps its content and becomes the window body, with the frame added around it.

Methods: open(), close(), isOpen(), setTitle(s), setButtons(list), maximize(on?), restore(), minimize(), center(), resize({width,height}), move({left,top}), window(), getBody(), destroy().

Two spellings

The modal flag decides everything, so it has a name at each end and you never have to remember which way round it goes:

card

CSS only — there is no behaviour to attach, so there is no Kob.card(). Compose the parts you need.

app shell

The bar across the top, the navigation down the side, and the scrolling area between them. CSS only — there is nothing to attach, because everything here is a class the page toggles for itself.

The column down the left is the one part of this frame that has state worth keeping — which entry is current, whether it is folded, what it does on a phone. Attach sidebar to it and that part is looked after; the markup below goes on working either way.

The whole thing running, with a grid, tabs and a stepper inside it, is the admin dashboard on the examples page.

sidebar

The navigation column of an application, and the three pieces of state it always turns out to need: which entry is current, whether it is folded to a rail, and what it does when the screen is too narrow to hold it at all.

Options

An entry

Methods

Events

From markup, or from data

The column itself is drawn by the stylesheet and always has been: a page that wants nothing but markup writes <nav class="kob-sidebar">, fills it with kob-sidebar-item links, and is finished — see app shell.

Give the widget items and it builds that markup for you. Leave them out and it adopts what is already there: your entries are indexed so select() and badge() can reach them, the one carrying active becomes the current entry, and your own click handlers go on working untouched. destroy() hands the markup back exactly as it was found.

Groups, headings and the bottom of the column

An entry with items becomes a group: a fold with a caret, aria-expanded on the head, and its children hidden — out of the tab order as well as out of sight — while it is shut. Choosing an entry inside a closed group opens it, because a mark nobody can see is no mark at all.

Nesting stops there, deliberately. Two levels is a menu; anything deeper is a tree, and this library already has one of those. A bare { title: '…' } is a heading rather than a fold, which is what most sections want, and { spacer: true } pushes the rest of the list to the bottom edge.

Folding, and what a phone gets instead

toggle() is the only call a menu button needs. On a wide screen it folds the column to a rail of icons; below breakpoint — 720px by default — it opens and closes a drawer. The button never has to know which screen it is on.

That distinction matters more than it sounds. The stylesheet's own answer at phone widths is the rail, and a rail is unreadable when it is all you have: eight icons and no labels. So below the breakpoint the column leaves the layout entirely — the shell gives the space back to the content — and returns as a panel over the page with its labels intact, a scrim behind it, Escape to dismiss, and the focus moved in and then handed back to the button that opened it.

menu

A list of commands in a floating panel: the dropdown behind a menu bar, the ribbon's split buttons, and any right-click menu.

Keyboard: the panel is a role="menu" and the focus moves into it when it opens. Up and Down walk the items (disabled ones are skipped, the list wraps), Home and End jump, Right opens a submenu and Left or Escape closes it, Enter or Space runs the item, Tab closes the lot. Escape hands the focus back to whatever had it. Checked items are menuitemcheckbox. showFor(anchor, { focus: 'first' }) and showAt(x, y, 'first') start on the first item, which is what opening from the keyboard should do.

Item shape

Methods: showFor(anchor, { side, gap }), showAt(x, y), bindContextMenu(element), hide(), isOpen(), setItems(items), panel().

menubar

The File / Edit / View strip. Once a menu is open, moving along the bar switches menus without a second click — what desktop menus do.

Keyboard: the bar is a role="menubar" with one tab stop. Left and Right move along it, Down, Enter or Space opens a menu on its first item, and Left or Right inside an open menu moves to the neighbouring menu. Escape closes and returns to the bar.

Methods: openMenu(i), closeMenu(), getMenu(i), setItems(items).

ribbon

Tabs of grouped commands. One large button, or a stack of small ones; a button with a menu opens it instead of firing.

Keyboard: the tab strip is a real tablist with one tab stop; Left, Right, Home and End move between tabs and open them, and each tab owns a tabpanel. A button with a menu is aria-haspopup="menu", and opens on its first item when pressed with Enter or Space.

Item keys: text, iconCls, size: 'large' | 'small', disabled, menu, onClick. Consecutive small buttons stack three to a column.

Methods: select(i), collapse(), expand(), toggleCollapse(), setTabs(tabs).

tree

Nodes are plain objects. Children may be an array, or left out with state: 'closed' to be fetched the first time the node opens.

Node shape

Methods: loadData, reload, expand(node), collapse(node), toggle(node), expandAll(), collapseAll(), select(node), getSelected(), find(id), check(node, on), getChecked(), walk(nodes, fn), getData().

Changing the tree

A tree that can only be read is half a widget: every application that shows one — a chart of accounts, a category tree, an org chart — sooner or later has to add a node to it. Doing that against the raw data and calling loadData() to redraw loses the open state of every branch on the way, so these five work on the same node objects the application handed over.

Dragging. With dnd: true, where a drop lands is decided by where in the row it happens: the top quarter puts the node above the target, the bottom quarter below it, and the middle half puts it inside. A tree that only ever dropped into things could not reorder siblings, which is most of what anybody drags a node for.

The keyboard. The tree is one tab stop, and the arrow keys move within it: down and up walk the nodes on screen, right opens a folder and then steps into it, left closes one and then steps out. Home and End go to the ends, Enter selects, and Space ticks when there are tick boxes. A tab stop per node would make a tree of four hundred nodes something nobody can tab past.

desktop

A windowed shell: wallpaper with launcher icons, a taskbar, a start menu, and one window per running app. Each window is a non-modal dialog, so dragging, resizing and maximising come from that widget — what the desktop adds is knowing what is running, which window has focus, and how to get a minimised one back. From the keyboard: Enter on a launcher icon opens its app, the start button is a menu button, and each task button is an aria-pressed toggle for the window in front.

Apps

An app says what its window contains, in one of three ways.

Options

Methods: open(id) returns the window's Dialog, plus close(id), closeAll(), minimize(id), getRunning(), getWindow(id), setApps(apps), setWallpaper(css).

datagrid

The whole result set lives in memory, and searching, filtering, sorting and paging all happen locally — so changing a filter never costs another round trip.

Options

Column definition

Methods

Events

Columns, and the widths they end up with

A width is a starting point rather than a contract. While the widths add up to less than the grid is wide, every column is stretched in proportion so the table fills its box — which is why a three-column grid never leaves a strip of empty background down the right. When they add up to more, the body scrolls sideways and the header follows it.

Drag one and that stops. A width set by hand is a decision, so the proportional stretch is switched off for good and only the last column — the one with no grip, because there is nothing to its right to give width back to — takes up the slack. The new width is written onto the column definition, so it survives sorting, paging and a reload, and onResizeColumn is where you would write it somewhere more permanent.

Filter chips

Above the header sits one chip per column. Each decides what to offer by looking at the data: a pick-list for categories, a lower bound for numbers, a contains box for free text.

They filter what the reader sees. A column with a formatter is flattened to text once per row and cached, so a status column rendering 1 as a green "Paid" badge filters and searches as Paid.

How a chip decides what kind it is

filter: 'number' on the column overrides the guess, filter: false drops that chip, and filterable: false on the grid drops the row. It also hides itself when there is nothing to choose between — fewer than two filterable columns, or a grid with no header.

Searching and sorting

The box in the footer matches every column that has a field, against the same flattened text the chips use — so a search for overdue finds the rows whose status badge reads Overdue, and a formatted 12,500.00 is found by typing 12,5. search(text) does the same from code, and fills the box in so the user can see what they are looking at.

Sorting compares numbers as numbers and everything else with localeCompare, which is what puts Ähnlich where a reader expects it rather than after Z. Null and undefined sort as an empty string. Unlike filtering, sorting reads the underlying value, not the formatter's output: a date rendered as 5 Jan 2026 still sorts by the ISO string behind it.

Selecting rows

One row at a time by default. checkbox: true or singleSelect: false turns multi-select on, and from there the gestures are the ones the desktop taught everyone:

The selection is kept as rows rather than as classes on whichever <tr>s exist at the moment, so it survives paging, sorting and filtering: rows picked on page one are still picked on page two, and getSelections() returns all of them. selectAll() means every row the filters let through, not the page on screen. loadData() clears it, because those rows are new objects.

Loading from a server

url fetches once, through Kob.config.request, and everything after that is local. There is no server-side paging protocol to implement: the grid asks for the result set, then does the searching, filtering, sorting and paging itself. A { rows, total } envelope is understood, as is a bare array or { data }; anything else is what loadFilter is for.

When the request fails the grid empties itself rather than leaving stale rows under a failed refresh, calls Kob.config.onRequestError, and then fires onLoadError. reload() refetches the same URL; reload('/api/other') or reload({ url, queryParams }) changes it and remembers the change.

Inline editing

beginEdit(i) turns the cells of that row into inputs — but only the columns that declared an editor; the rest stay as they are, which is how a key or a computed total is kept out of reach. A numberbox editor reads back as a number, rounded to its precision; a text one as a string.

endEdit(i) writes the inputs back into the row, redraws it and fires onEndEdit — which is where the save request belongs. cancelEdit() drops them without writing. Committing on Enter and abandoning on Escape is two lines in the page, not a built-in, because which key means "save" is an application's decision and not a widget's.

Totals, and columns that stay put

A column with a summary gets a value in a row along the bottom — sum, avg, count, min, max, a plain string used as a label, or a function handed the rows and returning whatever it likes. The row appears on its own as soon as one column asks for it.

Totals are taken over what the filters left, not over the page on screen. A footer that changed when you turned the page would be reporting on nothing anybody asked about. They sit in a table of their own under the body, so they stay put while the rows scroll and are not paged away with them, and a sum is shown through the column own formatter so the total reads in the same units the column does.

frozen: true on a leading column pins it while the rest scrolls sideways — the one thing a table of twenty columns cannot do without, since a row you cannot identify is a row you cannot read. Only a leading run can be frozen: a pinned column in the middle would slide under its neighbours on the way past. It is done with sticky cells in the one table rather than by drawing a second table over the first, which is where most grids keep their bugs — two tables mean two row heights to keep in step, two scroll positions, and a selection painted twice.

Editing and deleting from the row

Not every table has room for a column of buttons. rowActions gives you the actions without one: a strip that appears over a row when the pointer is on it, and parks on the row the user clicked so it stays reachable from the keyboard.

There is one strip, moved to whichever row wants it, rather than a copy per row: a grid repages and re-sorts constantly, and forty copies of the same three buttons is forty times the DOM for something only ever seen once. It hides itself when the row it belongs to scrolls out of the body's own viewport, so the buttons never end up floating over the header or the pager.

rowActionsOn: 'selected' drops the hover behaviour and shows the strip only on the selected row. Methods showRowActions(tr, hovering) and hideRowActions() drive it by hand.

A row that opens: invoice and its lines

detail is a function given a row and an empty <div> that has just been put under it. What goes in the div is up to you — a paragraph, a form, or, most often, a second datagrid holding the lines of the invoice the row is a header for. Setting the option adds the column of carets by itself.

Kob.datagrid('#invoices', {
  columns: [
    { field: 'no', title: 'Invoice', width: 120 },
    { field: 'customer', title: 'Customer' },
    { field: 'total', title: 'Total', align: 'right', summary: 'sum' }
  ],
  data: invoices,
  detail: function (row, panel) {
    Kob.datagrid(panel, {
      columns: [
        { field: 'sku', title: 'SKU', width: 110 },
        { field: 'name', title: 'Item' },
        { field: 'qty', title: 'Qty', align: 'right', width: 70 },
        { field: 'amount', title: 'Amount', align: 'right', width: 110, summary: 'sum' }
      ],
      url: '/api/invoices/' + row.id + '/lines',
      pagination: false
    });
  }
});

The function runs once per row, the first time that row is opened, and the panel it filled is then kept. Sorting, filtering and turning a page move the same element into the new table rather than calling you again — which matters, because for the shape this is for every call is a request to a server. Closing the panel is what throws it away, and everything KOB built inside it is destroyed with it.

This is not the treegrid, and the difference is worth being clear about. A treegrid's children are more rows of the same columns — the same table, indented. A detail panel is a different table entirely, with its own columns, its own totals and its own URL. Invoice lines are the second shape; a folder of files is the first.

One column, and it stops looking like a table

A grid of one column has nothing to sort against another, nothing to resize, and no second column to filter by — so it drops the header furniture and the chip row rather than showing controls that lead nowhere. What is left is a paged, searchable list whose rows look like whatever the formatter returns. showHeader: false does the same to a grid of many columns.

It is the same widget, so the search box, the pager, the row events, rowActions and the selection all still work. On a narrow screen this is often the shape a table wants to take.

Cell editors

A column's editor says what its cell turns into while the row is being edited. Eleven kinds are built in, and nine of them are the library's own field widgets put inside the cell — so a date in a table is picked off the same calendar it is picked off in a form, and a status is chosen from the same list. Anything else and a grid becomes a second, worse set of controls to learn.

rules and required on an editor are checked when the row is committed. A row that fails is not written back and its editors stay open — committing it would put a value the column has just called invalid into the data, and closing the editors would hide the only thing that can be fixed. The cell is outlined, carries the sentence as its title, and onEditError(index, row, errors) says which fields were refused.

Kob.registerEditor(name, factory) adds one of your own. The factory is handed the emptied cell, the spec from the column, and { row, index, column, grid }; whatever it returns is filled in with defaults, so an editor writes only the parts that are its own.

Kob.registerEditor('colour', function (td, spec) {
  var input = document.createElement('input');
  input.type = 'color';
  td.appendChild(input);
  return {
    node: input,
    getValue: function () { return input.value; },
    setValue: function (v) { input.value = v || '#000000'; }
  };
});

The keyboard, and the clipboard

The body takes one tab stop, and from there the arrow keys move a cell cursor around the page. A table of four hundred rows with a tab stop in every cell is a table nobody can tab past — and a screen reader announces the grid once rather than four hundred times.

The ring round the cursor's cell is drawn only while the keyboard is steering. A click still moves the cursor to the cell under the pointer, so the arrow keys carry on from there, but draws no ring — the row it lands on is already highlighted.

The cursor is a pair of indices rather than a reference to a <td>, because every sort, filter and page turn throws the cells away: it survives all three and lands on the same place in the new page. keyboard: false turns the lot off.

Choosing and moving columns

A table of twenty columns is only usable once it has been cut down to the six that matter. columnChooser: true puts a button at the end of the chip row that opens the list; reorderable: true lets a header be dragged sideways. Hiding a column keeps everything it had — its width, its filter, its formatter — because it is the same object with one flag changed.

A filter on a hidden column goes on filtering, which is deliberate: hiding the column you filtered by should not silently show you rows you had excluded. And the last visible column cannot be hidden — an empty table has no header to bring the others back from.

Remembering the layout

stateKey files the arrangement — widths, order, hidden columns, the sort and the page size — under a name, in this browser. Two grids that share a key share a layout, which is how the same table on two pages stays the same table. stateFilters: true remembers the chips as well; it is off by default because a filter somebody set three weeks ago is a table that looks broken on the way back to it.

getState() and setState() are the same data without the storage, for an application that would rather keep the layout on its own server against the user's account. resetState() forgets it and goes back to the columns as they were written.

Export and print

exportCsv(), exportExcel() and print() take the table out of the page — exportButton: true puts them behind a button in the chip row. Three decisions run through all three.

What gets exported is what the filters left, not the page on screen. A file holding twenty of four hundred rows because that is where the pager happened to be is wrong in a way nobody notices until it is in an invoice. rows: 'selected', 'page' or 'all' asks for something else.

Cells come out as the user reads them — a status column that renders 1 as a green "Paid" badge exports as Paid, for the same reason it filters as Paid. raw: true asks for the values underneath instead, and exportable: false on a column keeps it out of the file while leaving it on screen.

And the CSV carries a UTF-8 byte order mark and quotes any cell that opens with =, +, - or @. Both look like superstition and are not: without the first, Thai text arrives in Excel as mojibake; without the second, a spreadsheet treats a cell of data as a formula to run.

grid.exportCsv({ filename: 'rent-roll', rows: 'filtered' });
grid.exportExcel({ sheetName: 'September' });
grid.print({ title: 'Rent roll — September 2026' });

The spreadsheet is SpreadsheetML, which Excel, Google Sheets and LibreOffice all open and which keeps numbers as numbers. A real .xlsx is a zip archive, and building one would mean shipping a compressor in a library whose whole claim is that it has no dependencies. Printing goes through a hidden iframe rather than a popup window — nothing to be blocked — and prints a plain table: the chips, the pager, the row-action strip and the frozen columns are screen furniture and mean nothing on paper.

Grouping, and sorting by more than one column

Shift-clicking a second header sorts by it within the first, and the headers number the keys once there is more than one of them. A plain click still replaces the sort outright, so nothing changes for a grid that never multi-sorts.

groupField breaks the rows into groups under headings that fold. The grid sorts by that field first whatever else it is sorted by — groups that were interleaved would not be groups — and folding is taken off before paging, so a page always holds a full page of rows.

The menu on a row

rowMenu is a list of menu items, or a function of the row that returns one — because most of what a row menu offers depends on the row, and an invoice that is paid cannot be paid again. Handlers are called with (row, index).

The row under the pointer is selected first, unless it was already part of a selection: right-clicking one of five selected rows means those five, and a menu that quietly threw four of them away before running Delete would be a menu that destroys data.

Server-side mode

Local mode holds the whole result set, which is why filtering never costs a round trip — and is exactly why it stops working somewhere north of a hundred thousand rows. With remote: true every page turn, sort, chip and keystroke in the search box becomes a request, and the server answers with one page and a total.

What is sent is deliberately plain — page, rows, sort, order, q, filter — because the shape of somebody else's API is not something a widget gets to have an opinion about. remoteParams renames or reshapes the lot in one function when it disagrees.

Two details that matter. Late answers to old questions are dropped: a user typing in the search box has three requests in the air, and the slowest must not be the one that decides what is on screen. And the selection survives a page turn only when there is an idField — a remote grid never sees the same row object twice, so identity cannot carry it, and without an id the selection is honestly dropped rather than held against objects nothing on screen shares.

Virtual scrolling

virtual: true draws only the rows in the viewport, for the long unpaged list — a ledger, a log — where the pager is in the way rather than the point. Two spacer rows stand in for everything above and below, so the scrollbar is the right size and in the right place while the DOM holds a screenful.

It needs every row to be the same height, which is why rowHeight is a number and not a guess. A grid with groupField or detail set has rows of uneven height, so it pages normally instead and says so once in the console rather than drawing the table wrong.

Driving the grid from your own code

Every gesture the grid offers is a method underneath, and the chips and the footer are only one caller of them. A toolbar of your own, a keyboard shortcut or a route change can sort, search, filter, page and select exactly as a click does — and the matching event fires either way, so a status line has one place to listen.

A grid inside a tab, a panel or a dialog

Column widths are measured, and a grid built inside a hidden tab has nothing to measure. It watches its own box with a ResizeObserver and re-measures when the box changes, so in most cases this takes care of itself. The containers that hide and show their children — tabs, layout, panel, dialog — also fire a kob-resize event on what they reveal, which the grid listens for.

If a grid does turn up with collapsed columns after something outside the library changed the layout, resize() re-measures on demand. fit: true makes it fill its parent's height, which is usually what you want in a dialog or a layout region.

treegrid

A datagrid whose rows have children. A chart of accounts, a bill of materials, an org chart, a category tree with quantities against it — the shape half the tables in an internal system actually have. It is a role="treegrid": each row says its aria-level and whether it is aria-expanded.

It is the datagrid, not a second one

The tree is flattened into the same rows the grid already sorts, filters, pages, selects and edits, with a level recorded against each. What the tree adds is which rows are folded away, and a caret in one column. Everything else — the filter chips, the search box, the totals row, inline editing, rowActions, the selection surviving a page turn — goes on working, because none of it knows anything has changed.

Two things do behave differently, and both have to. Sorting orders siblings inside their parent rather than sorting the whole list, because a tree sorted flat is no longer a tree. Searching keeps the ancestors of a match: a row three levels down, on its own, does not tell the reader where it is.

A branch at a time

A chart of accounts arrives whole. An asset tree with eighty thousand leaves in it does not, and asking for a branch at the moment somebody opens it is the only way that screen is usable at all.

The row does not open until the children are there — a branch that flicks open empty and fills in a moment later reads as a bug — and the caret turns into a spinner in place while it waits, so nothing moves under the pointer. It is asked once: collapsing and re-opening uses what it already has. A branch whose fetch failed keeps its caret rather than turning into a leaf, so the next click tries again, and the error goes to Kob.config.onRequestError like every other request in the library.

Options

Every datagrid option applies as well.

Methods: expandRow(row), collapseRow(row), toggleRow(row), expandAll(), collapseAll(), revealRow(row) — open every ancestor of a row so it can be seen — getTree(), childrenOf(row), and the whole grid API underneath.

transfer

Two lists and the buttons between them. Assigning permissions to a role, members to a group, columns to an export: the job where a multi-select stops working somewhere around fifty options, because the question is not which of these but what does this end up with — and only two lists side by side answer that at a glance.

Options

Methods: getValue() — the ids on the right, in the order they were put there — setValue(ids), getSelections() for the rows rather than the ids, loadData(rows), clear(), isValid().

tooltip

The sentence a control cannot fit on itself. Internal systems are full of fields named after a policy nobody remembers and cells one word wider than their column; the native title attribute would do for both if it appeared inside a second rather than three, went where it could be read, and could be reached without a mouse.

Options

Methods: show(), hide(), toggle(), isOpen(), setContent(text).

popover and popconfirm

A small panel that belongs to one control. tooltip is a sentence you read; a popover is a panel you use — a title, a paragraph, a short form, a row of buttons. It stays open until it is dismissed, it is in the tab order, and a screen reader meets it as a dialog. popconfirm is the case most people want one for: "Delete this row?", asked beside the button that deletes it, without dimming the whole page the way a modal confirm does.

popover options

popconfirm options

Every popover option, and these. It defaults to position: 'top'.

Methods

timeline

Who did what, and when. Every record in an internal system eventually has to answer that: the trail an approval took, the states a document moved through, the audit log behind a number that changed. It is a role="list"; when onClickItem is set each entry takes the keyboard (Tab, then Enter or Space).

Options

tone takes success, danger, warn, info or accent and colours the mark. html renders rich content — a before and after, a link to the document — where text is plain. Methods: setItems, getItems, add(item, atEnd?), expand().

menubutton and splitbutton

A button with a menu hanging off it. The two differ on one question — does the button itself do anything? A menubutton is only a way in to the menu, so pressing it opens the menu. A splitbutton has a default action and the menu holds the alternatives to it: Save, with Save and print behind the caret.

Options

Both widgets take the same options.

Methods

Events

accordion

A stack of titled sections, one of them open. A long settings page, a filter column, a form split into parts that are filled in one at a time — anywhere the whole thing does not fit and the user only needs one part of it at once.

It reads your markup

Every direct child becomes a section. The header comes from the child's title attribute, or from a heading at the top of the block — an <h3> at the start of a section is how anyone would write this without a library, so it keeps working with one.

<div class="kob-accordion">
  <div title="Company">   … </div>
  <div><h3>Billing</h3> … </div>
</div>

items builds the same thing from data when the content is not yours to write by hand.

Options

Methods

Events: onSelect(index, title) and onUnselect(index, title).

slider

Pick a number, or a span of two, by dragging. Good for a value whose bounds mean something and whose exact digits do not — a price filter, a tolerance, a discount, a quality setting.

Options

Methods and events

getValue() returns a number, or [low, high] in range mode; setValue(v) takes either. getText() is the value through formatter. Also enable(), disable(), focus().

onSlide(value) fires while the handle moves; onChange(value) fires when it is let go. Hang a search off onChange, not onSlide — one drag across the track is dozens of onSlide calls and would be dozens of requests.

calendar

The month grid on its own, outside a dropdown. datebox is the right control when a date is one field on a form; this is for when the date is the screen — a booking sheet, a leave request, a day view that other panels follow. The grid is a real role="grid" with one tab stop: arrows move by day or week, PageUp and PageDown by month (with Shift, by year), Home and End to the ends of the week, and the grid turns the page when the cursor leaves the month. Every day is labelled with its full date.

Options

Methods

Events: onSelect(iso) fires on every click, onChange(iso) only when the date actually changed, and onMonthChange({ y, m }) when the grid moves — the one to hang "fetch this month's bookings" off.

propertygrid

Name and value, down the page, under headings. The settings screen, the details pane beside a record, the row of metadata nobody wants a whole form for.

It is the datagrid, with the columns decided

That is the whole trick: the search box, inline editing and everything else the datagrid does arrive already working. A settings page with sixty entries gets a search box for free, which is the difference between usable and not.

Options

A row may carry editor: 'numberbox' for its own kind of input, readonly: true to refuse editing whatever the sheet says, and formatter(value, row) to decide how it reads.

Methods

Events: onValueChange(row, value, was), plus every datagrid event.

messager and toasts

Each helper returns a promise, and still calls an old-style fn callback if you pass one.

icon takes 'info', 'warn' or 'error'; toast type takes 'success', 'error', 'warn' or 'info'. Pass html: true to let msg carry markup.

sweet

The big centred confirmation. Kob.alert and Kob.confirm draw a titled window, which is right for the dozens of small confirmations a data-entry app asks for. This is the other shape: one decision, front and centre, with a coloured mark that says at a glance whether the news is good.

Kob.sweet.success, .error, .warn, .info and .question are shorthands taking (title, msg) or the same options object.

statusbar

The strip along the bottom of a screen: what the app is doing, how many rows there are, who is signed in. CSS only — there is no widget to build and nothing to destroy.

combogrid

A field that picks a record out of a table. Type to search, look at three columns to be sure it is the right customer, pick it. A combobox shows one line per row, and one line is not enough to tell two customers named Somchai apart.

Methods: getValue(), setValue(id), getRow(), setRow(row), getText(), getGrid(), loadData(rows), reload(url), clear(), isValid().

The record, not only its id. getRow() hands back everything that was on screen — the credit terms, the address, the price band — because what an application does next almost always needs them, and fetching the row again to get them would be absurd when it was just in front of the user.

combotree

A field that picks a node out of a hierarchy: a department, a category, an account. Flattening a tree into a combobox loses the only thing that mattered — Sales under Bangkok is not Sales under Chiang Mai.

Methods: getValue(), setValue(v), getNode(), getText(), getTree(), loadData(nodes), reload(url), clear(), isValid().

tagbox

Free text, one chip at a time — keywords on a document, recipients on a message, labels on a ticket. The difference from a multiple combobox is the difference between choosing and writing: a combobox picks rows out of a list somebody else made, and this takes whatever is typed.

Methods: getValue(), setValue(list), add(tag), remove(tag), getText(), clear(), isValid().

Enter, a comma, or Tab commits a tag; Backspace on an empty field takes the last one back. A half-typed tag is committed on the way out of the field rather than thrown away — somebody who typed a keyword and tabbed on meant to add it.

rating

Stars, on a real <input type="range"> hidden under them. That is not a trick: it is the only way the field is reachable by keyboard, announced properly by a screen reader, and submitted by a plain form — all three of which a row of clickable spans loses.

Methods: getValue(), setValue(n), clear(), readonly(mode), enable(), disable().

colorpicker

A colour, chosen from a palette or typed as hex. Not a hue wheel: the colours an internal system needs picking are the ones in its own palette, and a wheel makes #7b7b7c possible — which is not a decision anybody meant to make.

Methods: getValue(), setValue(hex), clear(), isValid(). Kob.toHex(v) normalises any colour-shaped string.

The value crosses the API as a lowercase six-digit hex string, always: #ff0000, never red and never rgb(255,0,0). One shape means an application can compare two of them.

signature pad

A signature, drawn with a finger or a mouse — delivery notes, receipts, consent forms. Drawn at the device's pixel density so a capture on a phone is not a smear when it is printed, and kept as points rather than only as pixels, so it can be undone a stroke at a time and exported as vectors.

Methods: isEmpty(), clear(), undo(), toDataURL(type), toSVG(), getStrokes(), setStrokes(list), readonly(mode), resize().

SVG for anything that will be printed. A signature captured at 300 pixels wide and printed across a page is a smudge as a bitmap and exact as vectors, and toSVG() costs nothing extra because the strokes were kept as points anyway.

editor

A small rich text editor: bold, italic, lists, headings, links. The scope is fixed and deliberately narrow — a note on a ticket, terms on a quotation, a description on a product. Everything past that (tables, images, collaborative editing) is an editor project rather than a widget.

Methods: getValue(), setValue(html), getText(), insertHTML(html), clear(), focus(), readonly(mode), isValid(). Kob.sanitize(html) is the cleaner on its own.

Pasting and sanitising. HTML from Word or from a web page brings fonts, colours and class names that then have to be cleaned out of the database forever, so a paste arrives as plain text unless pasteHtml is on. And the value is sanitised on the way out as well: an editor that trusted its own contenteditable would hand back whatever a determined user managed to put in it, which is a stored XSS in every page that renders the result.

drawer

A panel that slides in from an edge — the other answer to "where does this form go?". A dialog takes the middle of the screen and everything behind it stops; a drawer keeps the list you were looking at in view, and is the right shape for the long thin things a record usually is.

Methods: open(), close(), toggle(), isOpen(), setTitle(text), setButtons(list), getPanel().

Same bones as the dialog: a mask, a focus trap, Escape to close, and the focus handed back to whatever opened it. The differences between the two are all geometry, and the parts that are easy to get wrong are the ones they share.

breadcrumb

Where you are, and the way back. The last entry is where you are: not a link, and marked aria-current, which is what tells a screen reader the difference.

Methods: setItems(list), getItems(), push(item), pop().

A long trail folds in the middle rather than wrapping onto a second line: the first entry and the last two are what people use, and the ones between them sit behind an ellipsis that opens them.

pagination

The pager, on its own — for the lists that are not grids. A page of cards, search results, a gallery, a report. It holds no data: it is told the total and asked what page it is on.

Methods: select(page), setTotal(n, keepPage), setPageSize(n), getPage(), getPageSize(), pageCount(), getRange().

Numbered pages rather than only next and back, because "page 7 of 25" is the only way somebody gets back to where they were yesterday. The run folds around wherever you are and keeps its width, so the buttons do not move under the pointer as you walk through them.

skeleton

The shape of what is coming, while it is still coming. A spinner says "wait"; a skeleton says "wait, and it will look like this" — which matters on a screen where what is loading is a table of forty rows.

Methods: replaceWith(content), and destroy() when the real thing arrives.

The shapes are aria-hidden with one live line beside them: "Loading" said once is useful, and forty grey rectangles announced one at a time is not.

avatar

A person, in a small round space. Without a photo — which on an internal system is most of the time — it draws initials on a colour derived from the name, so the same person is the same colour on every screen and in every session.

Methods: setName(n), setSrc(url), setStatus(s), getInitials(). Kob.initialsFor(name) and Kob.colorFor(name) are the two on their own.

Thai names are handled properly, which is why this is a widget rather than three lines of CSS. "First letter of each word" gives one letter for a name written as one word, and taking a single code point leaves a vowel mark stranded — initialsFor('สมชาย ใจดี') is สใ, with each consonant keeping the marks that belong to it.

tilegrid

A grid of tiles you tap: products on a till, rooms in a hotel, seats in a cinema, tables in a restaurant. The widget owns the layout, the selection, the state colours and the keyboard — and nothing about what a tile is. What goes inside is whatever render(item) returns, so one widget draws a photo and a price, a room number with a guest under it, or a bare seat label.

Methods: load(items), getItems(), getItem(id), add(item), remove(id), update(id, patch) (redraws just that tile), setBadge(id, n), getSelected() (items), getValue() (ids), setValue(ids), select(id), unselect(id), toggle(id), clearSelection(), filter(text | fn | null) (returns how many tiles are showing), enable(), disable().

Placing tiles. By default the grid places tiles itself, in order. For a plan — a cinema with an aisle, a floor of rooms — give items row and col (both 1-based, as in CSS grid) and optionally rowSpan and colSpan. Cells nobody claims stay empty, which is what makes the aisle.

Styling. Everything shape-related is a custom property on the element — --kob-tile-min, --kob-tile-gap, --kob-tile-aspect — so a project can restyle the grid in CSS without touching options. A tile is .kob-tile, with .kob-tile-selected, .kob-tile-disabled and .kob-tile-locked (drawn but not choosable) on it as they apply.

State is data, not mode: update it with update(id, { state: 'occupied' }), which redraws only that tile — a floor of rooms whose status changes every few seconds does not flicker.

descriptions

A record, read rather than edited — the other half of every record screen, and the half nobody ships. Written by hand it becomes a two-column table and a stylesheet per project, which is how one screen ends up with the labels bold and the next one has them grey.

Methods: setItems(list), getItems(), setValues(record).

A real <dl> underneath, because that is what this is — and because a screen reader then reads "Room, 101" as a pair rather than as two loose strings.

result

The page that says nothing is here, or that something went wrong. Every application has these four screens — empty, error, forbidden, done — and every application draws them differently, usually as a bare sentence in the middle of a white box.

Methods: set(spec) changes what it says without rebuilding it.

The actions are what this is really for. An empty state without one is a dead end, and "No invoices yet" with a New invoice button under it is the most useful screen in the application for somebody on their first day. An error or forbidden result is also announced as an alert; the others are a state of the page, not an interruption.

sparkline

A chart small enough to read as a word: the shape of a number over time, next to the number. Revenue in a KPI tile, stock movement in a grid cell, a trend beside a total. Inline SVG, and no dependency — which is the point, since a charting library is exactly what this library does not have.

Methods: setData(list), getData(), getValues().

The SVG is aria-hidden and the numbers are stated in text beside it — a picture of a trend says nothing to a screen reader, and "22, up from 4" does.

scheduler

A calendar with things in it. calendar is a month grid for picking a date; this is the other one — bookings, site visits, room occupancy, a delivery schedule — in month, week, day and agenda views.

Keyboard: every event is a button in the tab order and Enter or Space fires onEventClick; the toolbar is a toolbar whose view buttons carry aria-pressed, and the title is a live region. In the month view the days are a grid with one tab stop: arrows walk the days, and Enter or Space on a day fires onSlotClick exactly as clicking the empty part of it does. In the week and day views the empty slots are buttons with one tab stop for the whole grid (it starts at eight o'clock): Up and Down walk a day, Left and Right change day at the same hour, PageUp and PageDown move an hour, and Enter fires onSlotClick with the slot's start and end.

Methods: loadData(events), reload(url), addEvent(e), updateEvent(id, patch), removeEvent(id), getEvent(id), getEvents(), setView(v), goto(date), step(±1), getDate(), getRange().

Overlapping events share the width of their hour rather than covering each other. Two bookings at ten o'clock is exactly the case somebody is looking at the calendar to find, and a calendar that hides the second one is worse than no calendar. Times cross the API in one shape — ISO date, 24-hour time — whatever the locale displays, so a Buddhist-era calendar can never leak 2569 into the data.

React, Vue and Angular

kob-ui is not a component library — it builds DOM imperatively. That works inside any framework, on one condition: give it an element the framework will leave alone, and destroy the widget when that element goes away.

destroy() takes back every node the widget added and returns the element as it found it, so mounting again on the same element is safe — which is what React's StrictMode does in development, and what any router does when you revisit a screen.

React

filterbutton

The datagrid's filter chip, on its own — so a filter bar can sit above a chart, a card list, or anything else that is not a grid.

Methods: getValue(), setValue(v), clear(), setOptions(list).

alert

The banner that stays on the page — a validation summary above a form, a warning across the top of a screen.

Methods: setMessage(s), setType(t), close().

badge

Static badges are markup. The widget is for the ones that change — an unread count on a toolbar button, a status that flips as data arrives.

Methods: setText(v), getText(), setType(t), increment(by).

progressbar

A measured fill, or a sweeping stripe while the length of the job is unknown.

Methods: setValue(n), getValue(), indeterminate(on).

preloader and spinner

Over an element it is a busy mask; over <body> it is the splash the page shows before the application has drawn anything.

The spinner on its own is a class, with three sizes:

Methods: show(msg), hide(), isVisible(), setMessage(s).

A static element gets position: relative so the cover has something to sit against; destroy() puts that back.

Grid, flex and button groups

Enough layout CSS to lay out a form or a dashboard without reaching for a whole framework. Deliberately small.

The 12-column row

Below 720px every column takes the full width — one honest breakpoint rather than a matrix of per-size classes. For cards and tiles, kob-autogrid fits as many columns as it can:

Flex helpers

Button groups and toolbars

Keep selected on one member and the group reads as a segmented control. kob-btn-group-vertical stacks it.

kob-sep divides one group of commands from the next, and kob-spacer pushes what follows to the far end of the strip. For the desktop-application shape — a large glyph with its name underneath — see icon and caption on the button itself, and the worked toolbar beside it.

Custom widgets

Extend Kob.Widget and register it. From then on it behaves like a built-in: Kob.parse() builds it from markup, data-options works, and the accessor returns the instance.

Kob reference