On this page

Forms and text areas

The inputs group in isolenui/kit/inputs.h wraps your controls in labelled form rows, frames a field with addons, and adds a multiline text area and a select. It comes in through isolenui/kit/kit.h.

Field, a label, a control and its help text, drawn by isolenField, a label, a control and its help text, drawn by isolen
signup.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

#include <string.h>

struct signup {
    char email[128] = "";
    char site[128] = "";
    char bio[4096] = "";
    uint32_t plan = 0;
    bool bad_email = false;
    bool check_site = false;
};

static void form(ui::ctx* u, signup* s)
{
    // a label, the control, then a note or an error under it
    ui::field_spec email = ui::field_of("email").needed().about("we never share it");
    if (s->bad_email) {
        email.fails("that address has no @");
    }
    ui_form(u, email)
    {
        if (ui::text_box(u, "you@example.com", s->email, sizeof(s->email))) {
            s->bad_email = s->email[0] && !strchr(s->email, '@');
        }
    }

    // a prefix and a button round one bare field, all in one frame
    const ui::addon lead[] = { ui::addon_of("https://") };
    const ui::addon trail[] = { ui::addon_press("check") };
    ui::input_group_out out;
    ui_form(u, ui::field_of("website").beside(120.0f))
    {
        ui::input_group(u, "site", s->site, sizeof(s->site), lead, 1u, trail, 1u, 0u, &out);
    }
    // lead addons count first, so the trailing check is 1
    s->check_site = out.pressed == 1u;

    // grows from three rows to eight and shows a counter
    ui_form(u, ui::field_of("about you"))
    {
        ui::textarea(u, "bio", s->bio, sizeof(s->bio),
                     ui::textarea_of().hint("a few lines").lines(3u, 8u).grows().counted(500u));
    }

    static const char* const plans[] = { "free", "team", "studio" };
    ui_form(u, ui::field_of("plan"))
    {
        ui::native_select(u, "plan", plans, 3u, &s->plan);
    }
}

Form rows

form_begin(u, spec) and form_end, or the ui_form(u, spec) block, put a label above the control you declare inside, and a description or an error under it. A press on the label focuses the first control declared inside. Build the spec with field_of(label) and chain:

MethodFieldEffect
about(text)descriptionA small dim note under the control.
fails(text)errorShown in place of the note in the theme's error colour, and the label turns that colour too. An empty string counts as no error.
needed()requiredA red * after the label.
off()disabledDisables the whole row with style::disable and dims the label.
beside(w)label_wAbove zero puts the label beside the control, in a column w wide.

form_begin returns false when the row was dropped. Call form_end anyway, which the macro does. Rows nest up to 8 deep. Deeper ones still lay out but lose their notes, with a warning. label(u, text, required) is the label on its own, and returns true when pressed.

Input groups

input_group draws one frame round a bare text field and its addons. The frame shows the field's hover, focus and ring, and a press anywhere on the frame focuses the field. It is field_ex with field_bare always added, so the flags and the field_out in input_group_out::field work as on text editing. It returns true when the field's text changed. An overload takes a text_buf in place of the buffer and capacity, so the text has no length limit.

AddonMakes
addon_of(text)Dim text, such as a unit or a prefix.
addon_mark(icon, fallback)An icon in the dim text colour. With no live icon the fallback text shows.
addon_press(text, icon)A flat button, its own tab stop, that takes enter and space.

input_group_out::pressed is the button addon pressed this frame, counting the lead addons first and then the trail, or matrix_none. For content other than one field, open the frame yourself with input_group_begin and input_group_end, or the ui_input_group(u, label) block. The frame then shows focus for whatever inside holds it.

Text areas

textarea(u, label, buffer, capacity, spec) edits multiline text in your buffer as it is typed. Unlike text_box there is no working copy, and the return is true on every edit. textarea_run returns the edit_result bits of the frame instead: changed, moved, submit and cancel. Escape drops focus. The editor, its line cache and a 64 KB undo history live as long as the context, so a megabyte of text stays smooth.

textarea and textarea_run also take a text_buf. The editor is bound to it, so it grows as text is typed or pasted and is edited in place. Your own writes to it are picked up next frame, as they are for a buffer.

MethodFlag or fieldDefault and effect
hint(text)placeholderShown while empty. Null shows the label.
lines(shown, most)rows, max_rows4 rows. Growing stops at max_rows, 12 when zero.
grows()textarea_growThe height follows the line count between the two.
tabs()textarea_tabsTab types spaces and stays in the field. Shift tab still leaves.
counted(most)textarea_count, max_charsA counter under the text, n / most when a limit is set. The limit is in characters, and zero sets none.
locked()textarea_read_onlySelectable and copyable, not editable.
nowrap()textarea_nowrapLong lines run on instead of wrapping.

A text area keeps the wheel only while it has more to show, so a short one lets the view round it scroll. It has its own scroll bar, and it asks for the caret blink and the IME the same way the other fields do.

The text area notices when your code rewrites the buffer by sampling a few bytes from the head and across the text each frame. A rewrite it cannot see, such as one byte changed in the middle, needs textarea_reload(u, id). textarea_editor(u, id) hands you the live ui::edit, or null before its first frame. Give a text area a key if its position can change, since it warns and rebinds when its id moves.

Select

native_select is combo under the name forms ask for, with the same arguments and return. See text input.

kit.conf

None of these need a line. input_group and native_select call text_box.cpp and combo.cpp, which the linker pulls in on its own. See the component kit.

Last updated 6 October 2026