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.

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 three themes

Three 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 fourth theme is a block of your own. 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

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.

Options

Methods

Keyboard: arrows move through the list, Enter picks, Escape closes.

datebox

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

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().

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.

panel

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

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.

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, closable }), close(i).

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.

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.

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.

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.

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().

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.

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.

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.

Inline editing

Options

Column definition

Methods

Events

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.

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.

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.

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.

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