hb-input-array-tags

Category: inputs · Tags: inputs · Package: @htmlbricks/hb-input-array-tags

Summary

Bulma tag list input: value is Tag[] (id, label, optional metadata). Add via preset availableTags, free text (freeTag), or both; optional remove; setVal sync. schemaentry.params is optional in typings but you need availableTags and/or freeTag for the add UI.

Custom element

hb-input-array-tags

When to use it

Use this component when you need a multi-value string list with a stable id per chip (not only display text): skills, labels, filters, roles, or any set of tokens you want to serialize as JSON and validate as required or optional.

Value shape (Tag[])

Each entry is a Tag:

| Property | Type | Required | Description | |----------|------|----------|-------------| | id | string | Yes | Stable key; duplicates (same id) are not added twice. | | label | string | Yes | Text shown on the chip. | | type | string | No | Reserved for your own semantics (not used by the default UI). | | colorVarName | string | No | Same rules as params.colorVarName: Bulma semantic name, alias secondary, or --… CSS variable. Overrides field-level default when set. | | icon | string | No | Reserved for your own semantics (not used by the default UI). |

Initial selection is supplied as schemaentry.value (array of Tag). The component emits the current array on every meaningful change via setVal.

Custom element API

Attributes (host)

Web component attributes are strings. Pass structured data as a JSON string on schemaentry. Booleans in HTML attributes for this host use yes / no where noted.

| Attribute | Required | Description | |-----------|----------|-------------| | schemaentry | Yes | JSON object describing the field (see below). If missing or invalid JSON, nothing is rendered. | | show_validation | No | "yes" or "no" (default-like behavior when omitted is "no" in typings). When "yes" and the field is invalid, validationTip is shown. | | array_style | No | "pills" (default when omitted or any other value) or "area". area: Bulma textarea‑like region with squared tokens (trailing × when allowRemove) and an inline draft field; presets are filtered as you type into a custom suggestion panel (not Bulma’s dropdown markup), with “Add …” when freeTag is enabled. pills: original row of tags plus + / select / small input. | | id | No | Optional id on the host element. | | style | No | Optional inline styles on the host element. |

schemaentry object

The JSON object follows FormSchemaEntry for this control: shared form keys plus optional params as InputArrayTagsParams.

Required

• id — string; forwarded on setVal as detail.id.

Strongly recommended

• params — see next section (needs availableTags and/or freeTag for add UI).

Commonly used optional keys

• value — Tag[]; initial tags.
• required — boolean; when true, valid is false until at least one tag exists.
• disabled — boolean; disables add/remove and controls.
• validationTip — string; shown when show_validation is "yes" and the field is invalid.

Other keys from the shared form schema (label, placeholder, readonly, dependencies, etc.) may be present for consistency with hb-form or your app metadata; this component’s template focuses on tags, add controls, and validation help.

schemaentry.params (InputArrayTagsParams)

| Key | Type | Default | Description | |-----|------|---------|-------------| | availableTags | Tag[] | — | When non-empty, choosing “add” opens a <select> of presets (by id / label). | | freeTag | boolean | — | When true, users can add tags by typing (dedicated input or “New Tag” path from the select). | | colorVarName | string | — | Chip styling: Bulma semantic names get tag is-<name> (primary, link, info, success, warning, danger, dark, light, text, white, black), plus alias secondary → link. If the string starts with --, it is treated as a CSS custom property for background-color: var(<token>) with light text (legacy / custom themes). Per-tag colorVarName overrides the field default for that chip. | | allowRemove | boolean | — | When true, each chip gets a remove control (pills: Bulma delete; area: × on the squared token). | | addTagLabel | string | — | Label for the add chip; default +. Overridden by the add-tag-label slot when slotted. |

Add UI rules

• The add affordance is shown only if params.availableTags has length or params.freeTag is true.
• Presets only: availableTags set, freeTag false → add opens the select; choosing an option adds that tag.
• Free text only: no availableTags (or empty), freeTag true → add opens a small text field; Enter commits; Escape cancels.
• Both: select lists presets; if freeTag is true, an extra option “New Tag” (_custom) switches to the text input.
• Duplicates: a tag whose id already exists in value is not added again.

Commit vs blur (free-text input)

• Enter commits the trimmed input as a new tag (id and label both set to that string).
• A click outside the host (window listener, composedPath shadow-DOM aware) also commits trimmed text when the inline input is open.
• Blur on the inline input closes and clears without committing (use Enter or click-outside to save).

array_style="area" (textarea-like)

• Squared tokens (not Bulma pill tags) plus an inline text field sit inside a Bulma textarea shell; each token shows a trailing × when allowRemove is on. schemaentry.placeholder is used on the draft field.
• Suggestions list: unselected availableTags filtered by the current draft (id / label substring, case-insensitive). With freeTag, an extra row shows Add plus the draft in quotes when the draft is non-empty and not already selected. The list is a custom panel (hb-input-array-tags-suggest-*) with position: fixed: it anchors to the end of the draft text in the viewport (caret position does not move the panel), to the right when there is room (otherwise flipped to the left), and overlays the field so it stays clickable. Panel width follows the widest suggestion row (max-content), capped at the viewport. Layout updates on scroll (capture), resize, and typing. Styled with --bulma-* tokens so it survives Svelte WC CSS compilation (no reliance on Bulma dropdown-* class names in markup).
• Keyboard: Arrow Up/Down move the active row; Enter applies the active row, or the only match, or commits free text when freeTag; comma commits free text when freeTag and the draft is non-empty; Backspace on an empty draft removes the last chip; Escape clears the draft and closes the list.
• Mouse: choose a suggestion (mousedown uses preventDefault() so the field keeps focus). Click outside the host still commits trimmed free text (same window listener as pills) when freeTag is on.
• add-tag-label slot applies to the pills + control only, not the area field.

Events

| Event | detail | When | |-------|----------|------| | setVal | { value: Tag[]; valid: boolean; id: string } | Whenever value, valid, or field id changes in a way that affects the payload (internally deduplicated so identical payloads are not re-fired). |

Listen in plain DOM:

el.addEventListener("setVal", (e) => {
  const { value, valid, id } = e.detail;
});

Slots

| Slot | Description | |------|-------------| | add-tag-label | Light DOM content for the add control. When provided, replaces params.addTagLabel and the default +. |

Theming and ::part

Bulma CSS variables on :host control chrome and validation (see Bulma CSS variables). The catalog-style list maintained for tooling lives in extra/docs.ts (styleSetup.vars), including:

• --bulma-text, --bulma-text-weak — text and muted hints.
• --bulma-border — input/select borders.
• --bulma-danger — invalid help text.
• --bulma-link — interactive accents / focus alignment.
• --bulma-primary — default chip background when no colorVarName is set (Bulma is-light-style chips otherwise).

| CSS part | Description | |----------|-------------| | invalid-feedback | The p.help.is-danger node when show_validation is yes and the field is invalid. |

TypeScript types

Authoring types for apps and wrappers live in types/webcomponent.type.d.ts:

• Tag, InputArrayTagsParams, FormSchemaEntry, Component, Events

Examples

Minimal free-text tags (HTML)

<hb-input-array-tags
  schemaentry='{"id":"skills","params":{"freeTag":true,"allowRemove":true}}'
  show_validation="yes"
></hb-input-array-tags>

Presets + optional custom tag

<hb-input-array-tags
  schemaentry='{"id":"roles","required":true,"validationTip":"Pick at least one role.","params":{"availableTags":[{"id":"admin","label":"Admin"},{"id":"user","label":"User"}],"freeTag":true,"allowRemove":true,"addTagLabel":"Add"}}'
  show_validation="yes"
></hb-input-array-tags>

Initial value and themed chips

<hb-input-array-tags
  schemaentry='{"id":"labels","value":[{"id":"bug","label":"bug"},{"id":"feature","label":"feature"}],"params":{"freeTag":true,"allowRemove":true,"colorVarName":"--bulma-primary"}}'
></hb-input-array-tags>

Programmatic updates (JavaScript)

Assign a new JSON string to schemaentry when your field definition or initial value changes; the component syncs from the serialized schema when its fingerprint changes.

const el = document.querySelector("hb-input-array-tags");

el.setAttribute(
  "schemaentry",
  JSON.stringify({
    id: "tags",
    value: [{ id: "a", label: "Alpha" }],
    params: { freeTag: true, allowRemove: true },
  }),
);

Remember: from HTML, use attribute-safe JSON (single-quoted attribute, double quotes inside, or generate the string in code).

TypeScript

types/webcomponent.type.d.ts — schemaentry as string | FormSchemaEntry | undefined; params optional on FormSchemaEntry.

Build note (monorepo)

From the builder package root, a single-package web component build can be run with:

npm run build:wc -- input-array-tags

Use the full workspace pipeline when you need all packages or regenerated global element typings.