Tags Input
The Tags Input component allows users to create, select, and delete tags from a dropdown list. It supports both predefined options and user-created custom tags.
Properties​
Data​
| Property | Description | Expected Value |
|---|---|---|
| Label | The label text displayed for the field. | String (e.g., Tags, Categories) |
| Placeholder | Placeholder text shown when no tags are selected. | String (e.g., Add or select a tag) |
Tags​
Property | Description | Expected Value |
|---|---|---|
| Dynamic tags | Toggle to switch between static and dynamic options mode. When enabled, options are defined via a schema. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Options | List of tags shown when Dynamic tags is OFF. Click a tag to edit its Option label, Option value, Make this default option, Visibility and Disable settings. Click Add new option to add a tag, and drag tags to reorder them. Reordering resets Sort tags to None. | Configure each tag from the list. |
| Schema | JSON array defining tag options. Only visible when Dynamic tags is ON. | Array of objects with label, value, visible, default, and disable properties |
| Sort tags | Sort order for the predefined tags in the dropdown. | None, a-z or z-a |
| Allow new tags | When enabled, users can create new tags by typing values not in the predefined list. Enabled by default. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Tags loading state | When enabled, shows a loading indicator in the menu while options are being loaded. Only visible when Dynamic tags is ON. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Turn on search | When enabled, users can search/filter tags in the dropdown. When disabled, the dropdown menu does not appear and the component acts as a simple input field. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Search type | Sets whether the tag list is filtered in the browser (Client side) or by a query (Server side). Only visible when Turn on search is enabled. | Client side or Server side, or click on fx and enter an expression that resolves to a boolean ({{true}} for Server side). |
Dynamic Tags​
When Dynamic tags is enabled, use this schema format:
{{[
{ label: 'Newport', value: 'newport', visible: true, default: false, disable: false },
{ label: 'New York', value: 'new_york', visible: true, default: false, disable: false },
{ label: 'San Clemente', value: 'san_clemente', visible: true, default: true, disable: false }
]}}
| Schema Property | Description |
|---|---|
| label | Display text shown in the dropdown |
| value | Internal value stored when selected |
| visible | Whether the option is shown in the dropdown |
| default | Whether the option is pre-selected |
| disable | Whether the option is disabled (not selectable) |
Search​
Turn on Turn on search in the Tags section to let users search the tag list, then use Search type to choose where the filtering happens. When search is turned off, the dropdown menu does not appear and the component acts as a simple input field.
Client Side Search​
This is the default search option. The component filters the tags it already holds, in the browser. The complete tag list has to be loaded into the component for this to work.
Server Side Search​
When Search type is Server side, the component stops filtering the tags it holds in the browser, so the menu shows every tag it receives while the user types.
warning
Tags Input doesn't expose the text the user types or fire an event while they type, so a query can't react to the search text. Server side mode only turns off the in-browser filtering.
Sort tags still applies in Server side mode and re-sorts whatever the query returned, in the browser. Set it to none if your query already sorts the results.
Events​
| Event | Description |
|---|---|
| On tag added | Triggered when a tag is selected or a new tag is created. |
| On tag deleted | Triggered when a tag is removed from the selection. |
| On focus | Triggered when the user clicks inside the field. |
| On blur | Triggered when the user clicks outside the component while its dropdown is open. |
info
Check Action Reference docs to get detailed information about all the Actions.
Component Specific Actions (CSA)​
The following actions of the component can be controlled using the component-specific actions (CSA):
Action | Description | How To Access |
|---|---|---|
| Select Tags | Programmatically selects specified tags. Matches by value or label. | components.tagsinput1.selectTags |
| Deselect Tags | Programmatically removes specified tags from selection. Matches by value or label. | components.tagsinput1.deselectTags |
| Clear | Clears all selected tags. | components.tagsinput1.clear |
| Set visibility | Shows or hides the component. | components.tagsinput1.setVisibility |
| Set loading | Sets the loading state of the component. | components.tagsinput1.setLoading |
| Set disable | Enables or disables the component. | components.tagsinput1.setDisable |
Select Tags / Deselect Tags Input Formats​
Both selectTags and deselectTags support multiple input formats:
Format | Example | Description |
|---|---|---|
| Array of values | ['newport', 'new_york'] | Matches tags by their value property |
| Array of labels | ['Newport', 'New York'] | Matches tags by their label property |
| Array of objects with value | [{value: 'newport'}] | Explicitly match by value |
| Array of objects with label | [{label: 'Newport'}] | Explicitly match by label |
| Mixed formats | ['newport', {label: 'New York'}] | Combine different formats |
Matching Priority
Each string is matched against both the value and the label of every tag. The first tag in the list that matches either is selected. These actions don't trigger the On tag added or On tag deleted events.
Example Usage​
// Select by values
components.tagsinput1.selectTags(['newport', 'new_york'])
// Select by labels
components.tagsinput1.selectTags(['Newport', 'New York'])
// Select using objects
components.tagsinput1.selectTags([
{ value: 'newport' },
{ label: 'New York' }
])
// Deselect by label
components.tagsinput1.deselectTags(['Newport'])
// Deselect using mixed format
components.tagsinput1.deselectTags(['newport', { label: 'New York' }])
// Clear all selections
components.tagsinput1.clear()
// Hide the component
components.tagsinput1.setVisibility(false)
Exposed Variables​
Variable | Description | How To Access |
|---|---|---|
| values | Returns the array of values of selected tags. | components.tagsinput1.values |
| tags | Returns an array of {label, value} objects for all visible predefined tags. Excludes tags created by the user. | components.tagsinput1.tags |
| newTagsAdded | Returns an array of {label, value} objects for the tags created by the user. | components.tagsinput1.newTagsAdded |
| selectedTags | Returns the array of label and values of all the selected tags. | components.tagsinput1.selectedTags |
| label | The label text displayed for the field. | components.tagsinput1.label |
| isVisible | Returns the visibility state of the component. | components.tagsinput1.isVisible |
| isLoading | Returns the loading state of the component. | components.tagsinput1.isLoading |
| isDisabled | Returns the disabled state of the component. | components.tagsinput1.isDisabled |
| isMandatory | Returns whether the field is mandatory. | components.tagsinput1.isMandatory |
| isValid | Returns whether the current selection passes validation. | components.tagsinput1.isValid |
Example Usage​
// Get all selected values
{{components.tagsinput1.values}}
// Returns: ['newport', 'new_york']
// Get selected tags with labels
{{components.tagsinput1.selectedTags}}
// Returns: [{ label: 'Newport', value: 'newport' }, { label: 'New York', value: 'new_york' }]
// Get only user-created tags
{{components.tagsinput1.newTagsAdded}}
// Returns: [{ label: 'custom_tag_1', value: 'custom_tag_1' }, { label: 'custom_tag_2', value: 'custom_tag_2' }]
// Check if component is valid
{{components.tagsinput1.isValid}}
// Returns: true or false
Validation​
Validation Option | Description | Expected Value |
|---|---|---|
| Make this field mandatory | When enabled, the form cannot be submitted without at least one tag selected. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Custom validation | Custom validation rule using JavaScript expression. | JavaScript expression that returns a validation message or empty string |
Custom Validation Example​
{{components.tagsinput1.values.length >= 2 ? '' : 'Select at least 2 tags'}}
This validates that at least 2 tags are selected and shows an error message if not.
Additional Actions​
Property | Description | Configuration Options |
|---|---|---|
| Dynamic height | When enabled, the component height adjusts based on the number of selected tags. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Loading state | Shows a loading overlay on the entire component. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Visibility | Controls whether the component is visible. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Collapse when hidden | Collapses the component's space when it is hidden, so surrounding components fill the space. Takes effect when the app runs (preview or released app), not on the editor canvas. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Disable | When enabled, the component becomes non-interactive. | Enable/disable the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Tooltip | Provides additional information on hover. Supports Plain text, Markdown, and HTML formats. | String |
Devices​
Property | Description | Expected Value |
|---|---|---|
| Show on desktop | Makes the component visible in desktop view. | You can set it with the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
| Show on mobile | Makes the component visible in mobile view. | You can set it with the toggle button or dynamically configure the value by clicking on fx and entering a logical expression. |
Styles​
Label​
Property | Description | Configuration Options |
|---|---|---|
| Color | Label text color. | Select the color or click on fx and input code that programmatically returns a Hex color code. |
| Size | Sets the font size of the label, in pixels. Defaults to 12. | Enter a number or click on fx and enter code that returns a number. |
| Alignment | Label position relative to the field. | Side (left of field) or Top (above field). |
| Direction | Label alignment when using Side layout. | Left or Right. |
| Width | When Alignment is Side and Auto width is disabled, sets the label width. | Enter the value or use the slider. |
| Width type | Determines how label width is calculated. | Of component (percentage of total component width) or Of field (percentage of field width). |
Field​
Property | Description | Configuration Options |
|---|---|---|
| Background | Background color of the input field. | Select the color or click on fx and input code that programmatically returns a Hex color code. |
| Border | Border color of the input field. | Select the color or click on fx and input code that programmatically returns a Hex color code. |
| Accent | Color used for focus state and highlights. | Select the color or click on fx and input code that programmatically returns a Hex color code. |
| Auto pick chip color | When enabled, the component automatically assigns colors to chips from a predefined palette. | Enable/disable the checkbox. |
| Chip color | Background color of selected tag chips. Only visible when Auto pick chip color is OFF. | Select the color or click on fx and input code that programmatically returns a Hex color code. |
| Text color | Text color inside selected tags. Only visible when Auto pick chip color is OFF. | Select the color or click on fx and input code that programmatically returns a Hex color code. |
| Error text | Color for validation error messages. | Select the color or click on fx and input code that programmatically returns a Hex color code. |
| Border radius | Corner radius of the input field. | Enter the value in pixels. |
| Box shadow | Shadow effect around the component. | Select the box shadow color and adjust the related properties or set it programmatically using fx. |
Container​
Property | Description | Configuration Options |
|---|---|---|
| Padding | Padding around the component. | Default or None. |
Advanced​
Property | Description | Configuration Options |
|---|---|---|
| CSS class | Adds a custom CSS class to the component, which can be targeted using Custom Styles for advanced styling. | Enter one or more class names. |
info
The Advanced section is available only if your plan has the Custom Styles feature enabled.
Need Help?​
- Reach out via our Slack Community
- Or email us at support@tooljet.com
- Found a bug? Please report it via GitHub Issues