tom_select_box(), tags_box() form()

Select with search, groups, several values or a remote search (tom_select_box()), and free tags in one field (tags_box()), on Tom Select without jQuery.

form()->tom_select_box($name, $values = [], $extra = [], $replace = [])
form()->tags_box($name, $values = [], $extra = [], $replace = [])

Options

OptionMeaning
placeholder, allow_clear, translateEmpty text; a clear button; translate the labels.
multiple, max_itemsSeveral values (name[]); at most N.
ajax_url, ajax_param, ajax_min, ajax_limit, ajax_labelsRemote search: GET URL answering [{value, text}], query parameter (q), letters before searching (1), rows (50), callable that labels the stored values.
max_tags, tag_max_length, createtags_box(): limits (0 / 50); false: suggestions only.
configRaw Tom Select settings over what form2 builds (data only); site-wide $PROJECT_CONF['html_tom_select']['CONFIG'].
disabled, required, class, class_add, id, attr, data-*As for input(); attr cannot set on*, name or id.

Example

Code

$sizes = ['Clothes' => ['s' => 'S', 'm' => 'M', 'l' => 'L'], 'Shoes' => ['40' => '40', '41' => '41']];
$colors = ['red' => 'Red', 'green' => 'Green', 'blue' => 'Blue', 'black' => 'Black'];
return form(['size' => 'm', 'colors' => ['red', 'blue'], 'tags' => 'php,htmx'])
    ->tom_select_box('size', $sizes, ['placeholder' => 'Pick a size', 'allow_clear' => 1])
    ->tom_select_box('colors', $colors, ['multiple' => 1, 'max_items' => 3])
    ->tags_box('tags', ['php', 'htmx', 'mysql', 'redis'], ['max_tags' => 5]);

Notes

  • The field is a plain <select> / <input> that posts without JavaScript; options travel as JSON in data-yf-select, the yf_select asset starts it (also in content htmx swaps in).
  • Tags post as one comma-separated string; read them with html()->tom_select_tags() (trimmed, unique, limits enforced again).
  • A remote search endpoint only reads (GET, no token): cut the query with html()->tom_select_query(), answer with html()->tom_select_send(); see the demo.
  • Labels are always text: escaped in the markup and rendered as text by Tom Select.

Bootstrap 3 and 5

The bootstrap5 theme under Bootstrap 5 (follows data-bs-theme), the default theme with Bootstrap 3 fixes otherwise; errors mark the row (3) or the control (5).

See also: html/tom_select_box, demo:form/tom_select, form/select_box