Tags for Bootstrap 4/5

How to use

An ES6 native replacement for select using standards Bootstrap 5 (and 4) styles.

(almost) No additional CSS needed! Supports creation of new tags.

1import Tags from "./tags.js";
2Tags.init();
3// Tags.init(selector, opts);
4// You can pass global settings in opts that will apply
5// to all Tags instances

By default, only provided options are available. Validation error will be displayed in case of invalid tag.

1<label for="tags-input" class="form-label">Tags</label>
2<select class="form-select" id="tags-input" name="tags[]" multiple>
3  <option disabled hidden value="">Choose a tag...</option>
4  <option value="1" selected="selected">Apple</option>
5  <option value="2">Banana</option>
6  <option value="3">Orange</option>
7</select>
8<div class="invalid-feedback">Please select a valid tag.</div>

Creation of new tags

Use attribute data-allow-new to allow creation of new tags. Their default value will be equal to the text. Since you can enter arbitrary text, no validation will occur.

1<select class="form-select" id="tags-input" name="tags[]" multiple data-allow-new="true"></select>

You can force these new tags to respect a given regex.

NOTE: don't forget the [] if you need multiple values!

Server side support

You can also use options provided by the server. This script expects a json response that is an array or an object with the data key containing an array.

Simply set data-server where your endpoint is located. It should provide an array of value/label objects. The suggestions will be populated upon init except if data-live-server is set, in which case, it will be populated on type. A ?query= parameter is passed along with the current value of the searchInput.

You can preselect values either by using data-selected or by marking the suggestion as selected in the json result.

1<label for="validationTagsJson" class="form-label">Tags (server side)</label>
2<select
3  class="form-select"
4  id="validationTagsJson"
5  name="tags_json[]"
6  multiple
7  data-allow-new="true"
8  data-server="demo.json"
9  data-live-server="1"
10>
11  <option disabled hidden value="">Choose a tag...</option>
12</select>

You can pass additionnal parameters with data-server-params and choose the method with data-server-method (GET or POST).

Setting data programmatically

You can use the items config key to pass options. These will be added to the select object. Items can be an array of Suggestions, or a key:value object.

You can also call setData manually.

Options

Options can be either passed to the constructor (eg: optionName) or in data-option-name format. You can also use the data-config attribute with a json encoded string.

Name	Type	Description
items	Array.<(Suggestion|SuggestionGroup)>	Source items
allowNew	Boolean	Allows creation of new tags
showAllSuggestions	Boolean	Show all suggestions even if they don't match. Disables validation.
badgeStyle	String	Color of the badge (color can be configured per option as well)
allowClear	Boolean	Show a clear icon
clearEnd	Boolean	Place clear icon at the end
selected	Array	A list of initially selected values
regex	String	Regex for new tags
separator	Array | String	A list (pipe separated) of characters that should act as separator (default is using enter key)
max	Number	Limit to a maximum of tags (0 = no limit)
placeholder	String	Provides a placeholder if none are provided as the first empty option
clearLabel	String	Text as clear tooltip
searchLabel	String	Default placeholder
showDropIcon	Boolean	Show dropdown icon
keepOpen	Boolean	Keep suggestions open after selection, clear on focus out
allowSame	Boolean	Allow same tags used multiple times
baseClass	String	Customize the class applied to badges
addOnBlur	Boolean	Add new tags on blur (only if allowNew is enabled)
showDisabled	Boolean	Show disabled tags
hideNativeValidation	Boolean	Hide native validation tooltips
suggestionsThreshold	Number	Number of chars required to show suggestions
maximumItems	Number	Maximum number of items to display
autoselectFirst	Boolean	Always select the first item
updateOnSelect	Boolean	Update input value on selection (doesn't play nice with autoselectFirst)
highlightTyped	Boolean	Highlight matched part of the suggestion
highlightClass	String	Class applied to the mark element
fullWidth	Boolean	Match the width on the input field
fixed	Boolean	Use fixed positioning (solve overflow issues)
fuzzy	Boolean	Fuzzy search
startsWith	Boolean	Must start with the string. Defaults to false (it matches any position).
singleBadge	Boolean	Show badge for single elements
activeClasses	Array	By default: ["bg-primary", "text-white"]
labelField	String	Key for the label
valueField	String	Key for the value
searchFields	Array	Key for the search
queryParam	String	Name of the param passed to endpoint (query by default)
server	String	Endpoint for data provider
serverMethod	String	HTTP request method for data provider, default is GET
serverParams	String | Object	Parameters to pass along to the server. You can specify a "related" key with the id of a related field.
serverDataKey	String	By default: data
fetchOptions	Object	Any other fetch options (https://developer.mozilla.org/en-US/docs/Web/API/fetch#syntax)
liveServer	Boolean	Should the endpoint be called each time on input
noCache	Boolean	Prevent caching by appending a timestamp
allowHtml	Boolean	Allow html in input (can lead to script injection)
inputFilter	function	Function to filter input
sanitizer	function	Alternative function to sanitize content
debounceTime	Number	Debounce time for live server
notFoundMessage	String	Display a no suggestions found message. Leave empty to disable
onRenderItem	RenderCallback	Callback function that returns the suggestion
onSelectItem	ItemCallback	Callback function to call on selection
onClearItem	ValueCallback	Callback function to call on clear
onCreateItem	CreateCallback	Callback function when an item is created
onBlur	EventCallback	Callback function on blur
onDataLoaded	DataCallback	Callback function on data load
onFocus	EventCallback	Callback function on focus
onCanAdd	AddCallback	Callback function to validate item. Return false to show validation message.
onServerResponse	ServerCallback	Callback function to process server response. Must return a Promise
onServerError	ErrorCallback	Callback function to process server errors.
confirmClear	ModalItemCallback	Allow modal confirmation of clear. Must return a Promise
confirmAdd	ModalItemCallback	Allow modal confirmation of add. Must return a Promise

Any of these config option can be changed later with setConfig.

To know more about these features, check the demo!

Callbacks

DataCallback ⇒ void

Param	Type
src	*
inst	Tags

EventCallback ⇒ void

Param	Type
event	Event
inst	Tags

ServerCallback ⇒ Promise

Param	Type
response	Response

ErrorCallback ⇒ void

Param	Type
e	Error
signal	AbortSignal
inst	Tags

ModalItemCallback ⇒ Promise

Param	Type
label	String
inst	Tags

RenderCallback ⇒ String

Param	Type
item	Suggestion
label	String
inst	Tags

ItemCallback ⇒ void

Param	Type
item	Suggestion
inst	Tags

ValueCallback ⇒ void

Param	Type
value	String
inst	Tags

AddCallback ⇒ void | Boolean

Param	Type
value	String
data	Object
inst	Tags

CreateCallback ⇒ void

Param	Type
option	HTMLOptionElement
inst	Tags

Tips

• You can also use it on single selects! :-)
• Use arrow down to show dropdown
• If you have a really long list of options, a scrollbar will be used
• Access Tags instance on a given element with Tags.getInstance(mySelect)

Custom events

• tags.blur is fired alongside onBlur
• tags.loaded is fired alongside onDataLoaded

Style

While styling is not mandatory, some pseudo styles may help align your styles with a regular bootstrap form-control We basically replicate input state as pseudo classes on the form-control container

• Support focus styles by implementing a pseudo class form-control-focus
• Support improved floating labels by implementing a pseudo class form-placeholder-shown
• Support disabled styles by implementing a pseudo class form-control-disabled

These styles can be found in _tags.scss

You can also use the tags-pure.scss file which provide you a css vars only version of the required styles (works well with bootstrap 5.3)

Colors

You can set badge classes or styles using data-badge-style or data-badge-class attributes. You can also pick arbitrary colors using data-background-color and data-color.

These can also be used programmaticaly

1[
2    {
3        "value": "1",
4        "label": "Label 1",
5        "data": {
6            "backgroundColor": "#832f2f",
7            "color": "#7b932f"
8        }
9    },
10    {
11        "value": "2",
12        "label": "Label 2",
13        "data": {
14            "backgroundColor": "#2115c1",
15            "color": "#7b932f"
16        }
17    }
18]

Without Bootstrap 5

Bootstrap 4 support

Even if it was not the initial idea to support Bootstrap 4, this component is now compatible with Bootstrap 4 because it only requires minimal changes.

Check out demo-bs4.html

Standalone usage

Obviously, this package works great with the full bootstrap library, but you can also use it without Bootstrap or with a trimmed down version of it

Actually, this library doesn't even use the js library to position the dropdown menu, so its only dependencies is on css classes. You can check out the .scss file to see how to reduce bootstrap 5 css to a smaller size.

Check out demo-standalone.html

Demo

https://codepen.io/lekoalabe/pen/ExWYEqx

How does it look ?

Do you need to init this automagically ?

You can now use this as a custom element as part of my Formidable Elements collection.

Or you can use Modular Behaviour (see demo)

Browser supports

Modern browsers (edge, chrome, firefox, safari... not IE11). Add a warning if necessary.

Also check out

• Bootstrap5 autocomplete: the autocomplete input for bootstrap 5 (and more!)
• BS Companion: the perfect bootstrap companion
• Admini: the minimalistic bootstrap 5 admin panel

How to contribute

If you want to make a PR, please make your changes in tags.js and do not commit any build files They will be updated upon release of a new version.

If you want to test your changes, simply run npm start and test in demo.html (feel free to add new test cases).

For scss updates, apply changes to scss files. They need to be compiled manually since they are not meant to be used by themselves.