TagsField
Introduction
The TagsField component is an interactive tag-entry control that allows users to type and manage a list of text tags or badges. It supports intuitive keyboard mappings (such as committing on Enter and deleting on Backspace), item-scoped delete triggers, and comes with the same standard label, helper, and invalid error text support as other field inputs.
The TagsField is fully integrated as a tagsField (alias tagsInput) block in the Page Builder, allowing content authors and developers to configure default visual labels, helper instructions, sizing scales, and color themes directly within the CMS.
Usage via CMS Page Builder (JSON)
These examples illustrate how content editors bind and structure interactive tag inputs inside the JSON page schemas (content/pages/*.json).
1. Standard Tags List Input
A standard tag entry input loaded with initial default tags, complete with visual helper instructions underneath the input box.
{
"type": "tagsField",
"label": "Development Skills",
"helperText": "Press Enter or comma to commit a tag",
"defaultValue": ["React", "Hono", "Vite"],
"interactive": true
}
2. Accented Sizing & Visual Style (Subtle Variant)
Features a subtle background card variant and larger visual sizing, customized with a themed color palette for active badges.
{
"type": "tagsField",
"label": "Property Amenities",
"defaultValue": ["WiFi", "Pool"],
"variant": "subtle",
"size": "lg",
"colorPalette": "purple",
"interactive": true
}
CMS Configuration Reference
These fields map directly to Sveltia CMS block properties under public/admin/config.yml or the Page Builder configurations:
| Property | CMS Field Type | Default | Description / Supported Options |
|---|---|---|---|
Label Text (label) | string | - | The visual text title rendered directly above the tag-entry box. |
Helper Text (helperText) | string | - | Small instruction text displayed underneath the control (e.g. "Press Enter to add"). |
Error Text (errorText) | string | - | Warning text displayed underneath when the input state is toggled to invalid. |
Initial Tags (defaultValue) | list | [] | List of string values representing tags that are pre-populated upon loading. |
Current Tags (value) | list | - | List of string values representing the current tags in the input (controlled). |
Input Name (name) | string | - | Form association name of the underlying field, submitting comma-joined values natively. |
Visual Style (variant) | select | "outline" | Visual background and border styling. • Options: "outline", "subtle", "surface". |
Size Scale (size) | select | "md" | Controls overall height, padding, and badge sizes. • Options: "xs", "sm", "md", "lg". |
Color Theme (colorPalette) | select | "green" | Visual color accent applied to active tags. • Options: blue, green, red, purple, orange, amber, cyan, slate. |
Disabled (disabled) | boolean | false | Disables user interaction, dims the styling, and hides the delete buttons. |
Read Only (readOnly) | boolean | false | Converts the tags into a static list by hiding the entry text-input entirely. |
Force Interactive (interactive) | boolean | true | Hydrates the component as an interactive client-side island to capture keyboard events and manage lists. |
Developer Notes & Accessibility
- Keyboard Interaction Mechanics: Renders a highly responsive keyboard-friendly field:
- Pressing
Enteror keying a comma immediately commits the current text as a new tag and clears the text input (duplicate entries are automatically ignored). - Pressing
Backspacewhen the text input is empty deletes the last tag in the list. - Clicking anywhere inside the outer container that is not a tag automatically focuses the text cursor.
- Pressing
- WAI-ARIA Accessibility Standards: Renders robust accessibility markup:
- The root container acts as an accessible group, managing aria-describedby associations dynamically.
- Each tag inside the control gets a focusable close trigger with descriptive
aria-labeltags, ensuring standard screen reader interaction works cleanly.
- Hidden Input Form Mapping: Outputs a native hidden
<input>element with comma-joined values ("React,Hono"). This ensures standard HTML form submissions and server POST actions capture current selections out-of-the-box.