On this page

The component kit

Every widget lives in isolenui/src/kit, one .cpp per component, built into one static library. An app includes isolenui/kit/kit.h and calls what it needs. The linker drops the rest.

Headers

Include isolenui/kit/kit.h to use the kit. isolenui/ui/ui.h no longer includes it. kit.h includes one header per group, and every call is in namespace ui, so an app never includes a group header itself. A group header only declares.

HeaderHolds
isolenui/kit/controls.hButtons, checkbox, toggle, radio, tabs, segmented, slider, drag, stepper, text and search boxes, field_ex, combo and collapsible. See widgets.
isolenui/kit/readouts.hLabel and value rows, badge, dot, progress, meter, sparkline and bars.
isolenui/kit/chrome.htitle_bar and ui::chrome.
isolenui/kit/pickers.hCalendars, date, range, time and date time pickers, colour, roller, code cells and spin box. See calendars and dates.
isolenui/kit/charts.hCharts, rich text spans, animated images, image buttons and app textures. See charts.
isolenui/kit/containers.hPager, carousel, tab view, tile view, split, accordion, scroll area and sidebar.
isolenui/kit/inputs.hScale, fields and labels, checkbox and radio groups, switches, button and toggle groups, matrix, arcs, range and vertical sliders, input group, textarea, native select and the on screen keyboard.
isolenui/kit/menus.hMenus, dropdown, context menu, menubar, select, navigation menu, fuzzy search, command palette, comboboxes, popover, hover card, tooltip, dialogs, sheet, drawer and toast. See menus.
isolenui/kit/data.hTables and data tables, items, list and tree views, cards, alerts, empty states, type styles, loading marks, avatars, breadcrumb and pagination. See tables.
isolenui/kit/chat.hMessage scroller, messages, bubbles, markers, attachments, shimmer and a questionnaire. See chat.
order.cpp
#include "isolenui/app/app.h"
#include "isolenui/kit/kit.h"

// ui.h brings in every kit group, only what is called here is linked
struct form {
    bool notify = true;
    int32_t day = ui::k_no_day;
    int32_t copies = 1;
};

static void view(isolen_frame* f, void* user)
{
    form* s = static_cast<form*>(user);
    ui::ctx* u = f->ui;
    ui_box(u, ui::col().grow().pad(24.0f).gap(12.0f))
    {
        // controls.h, toggle.cpp
        ui::toggle(u, "notify me", &s->notify);
        // pickers.h, date_picker.cpp pulls in calendar.cpp and text_box.cpp
        ui::date_picker(u, "ship on", &s->day);
        // pickers.h, spinbox.cpp
        ui::spinbox(u, "copies", &s->copies, 1, 99);
    }
}

int main(int argc, char** argv)
{
    static form s;
    isolen_app_desc d = isolen_app_defaults();
    d.title = "order";
    d.view = view;
    d.user = &s;
    return isolen_run(&d, argc, argv);
}

Every component

3D Model Viewera gltf model on an orbit camera
3D Texturea texture from a 3d pass
Accordionstacked sections that open one or many at a time
Alerta callout that draws attention to a message
Alert Dialoga modal that interrupts and waits for an answer
Animation Imageframes played as a picture
Arca value on a circular track
Aspect Ratioholds content to a width over height ratio
Attachmenta file or media chip inside a message
Avatara picture of a person with a fallback
Breadcrumbwhere the page sits in a hierarchy
Bubblethe shaped body of a chat message
Button Groupbuttons joined into one control
Button Matrixa grid of buttons from one table
Calendara month grid to pick a day or a range
Carda framed block with a header, body and footer
Carouselslides that snap one after another
Chartlines, areas and bars over axes
Colour Pickerpicks a colour
Comboboxa text field with a filtered list of choices
Commanda searchable palette of actions
Context Menua menu that opens under the pointer
Data Tablea table that sorts, filters and pages
Date Pickera field that opens a calendar
Date Time Pickera date field and a time field as one value
Dialoga window over the page
Drawera panel that slides up from an edge
Dropdown Menua menu opened by a trigger
Emptywhat a view shows when it has nothing
Fielda label, a control and its help text
GIFan animated gif
Hover Carda preview that opens when the pointer rests
Image Buttona button drawn from pictures
Input Groupan input with addons joined on
Input OTPone time code boxes
Itema row with media, content and actions
Kbda key or shortcut
Keyboardan on screen keyboard
Labelthe name of a control
Lottiea lottie animation
Markera divider inside a message stream
Menua menu with pages and sub pages
Menubara bar of menus like a desktop app
Messageone entry of a conversation
Message Boxa small modal with buttons
Message Scrollera conversation that keeps to the newest
Native Selectthe platform select
Navigation Menusite links with panels
Pagerpages that snap as you swipe or page
Paginationmoves between pages of results
Questionnairea guided set of questions
Resizablepanes split by handles
Rollera wheel of options
Scaleticks and labels along a line or arc
Selecta list of options behind a trigger
Sheeta panel that slides in from a side
Sidebarthe navigation column of an app
Skeletona placeholder while content loads
Span Grouprich text from styled spans
Spinboxa number with steps per digit
Spinnershows that work is running
Tab Viewtabs with their own pages
Tablerows and columns of data
Tile Viewpages laid out on a grid that swipe
Time Pickerpicks a time of day
Toasta short message that goes away by itself
Togglea button that stays pressed
Toggle Groupa set of toggles
Tree Viewa hierarchy that folds

One file per component

A component is named after its file: toggle.cpp is the toggle component and date_picker.cpp is date_picker. A file can hold a few calls that belong together, such as button, button_accent and icon_button in button.cpp. kit_control.cpp and kit_paint.cpp hold the helpers components share. They come in only when a component that uses them does.

The small marks the kit paints, the checkbox and menu ticks and the chevrons on collapsibles, selects, breadcrumbs, trees and sidebars, are vector strokes: antialiased polylines with round caps from the draw list, so they stay crisp at any scale and under pinch zoom.

cmake/kit.cmake globs every isolenui/src/kit/*.cpp into isolen_kit. A new component is a new file and needs no build change.

How unused components are stripped

Each app is linked against the static isolen_kit library, so the linker only pulls the objects an app calls into. The flags below drop what is left down to the function.

ToolchainCompileLink
MSVC, release/Gy /Gw, each function and global in its own section/OPT:REF /OPT:ICF, drop unreferenced sections and fold identical ones
clang on mac-ffunction-sections -fdata-sections on the kit-Wl,-dead_strip, since Mach-O already splits every symbol

isolenui_app(target) applies all of this to every app through isolenui_link_kit(target). Configure logs one line with the file count, the files kept by name and the components switched off.

kit.conf

kit.conf at the root of isolenui only gates what the linker cannot work out alone. A component with no third party code needs no line. Each line is a component name followed by keys, and # starts a comment.

KeyEffect
offLeaves its files out, so any call to it fails to link instead of doing nothing. Every component that needs it goes off too, and configure says why.
onUndoes an earlier off on the same line.
needs a bOther components it calls. A name not listed elsewhere is added with its defaults.
files a.cpp b.cppIts source files, when they are not just its name. Paths are relative to isolenui/src/kit; a file outside it is brought into the build only while the component is on. A missing file stops configure. On mac a _vk.cpp file is left out, and elsewhere a .mm file is.
libs xLibraries linked with the kit when the component is on, such as elba and capri for lottie, doga for gif and corfu for model_view.
assets pathRepo files copied into assets beside every app.
namedIts objects go into every app directly, for a component that registers itself from a static initializer and so has no call for the linker to follow. gif is named, so every app knows GIF bytes before main runs. A host with no gfx device, such as the setup stub, links with isolen_link_kit(target no_named) and keeps only what it calls.

The lines in the file today are the components that build on other components, and the three that bring code from outside isolenui/src/kit:

kit.conf
date_picker  needs calendar text_box
date_time_picker  needs date_picker time_picker
colour_picker  needs text_box
carousel  needs pager
tile_view  needs pager
tab_view  needs pager tabs
accordion  needs collapsible
scale  needs chart
card  needs typography
empty_state  needs typography button
gif  named  needs animimg spinner  libs doga
lottie  needs animimg  libs elba capri
model_view  libs corfu

So text_box off would switch off date_picker, date_time_picker and colour_picker too. A name that is not lowercase letters, digits and underscores, a name listed twice, or a word that follows no key is a configure error with its line number.

Switching a component off is a build choice, not a runtime one. The call is still declared, so code that uses it fails at link time and never silently draws nothing.

Coming next

Every declared component is built. See the roadmap for what is in progress.

Last updated 6 October 2026