Configuration Reference

All DotSelect configuration is done through HTML data attributes on the <select> element. This page provides a complete reference of every available attribute.

Core

Attribute	Description	Type	Default
data-dot-select	Enables DotSelect on the element	flag	—
data-placeholder	Placeholder text when no value is selected	string	""
data-searchable	Enable the search input	boolean	false
data-allow-clear	Show a clear button to reset the value	boolean	false
data-close-on-select	Close dropdown after selection	boolean	true (single), false (multiple)
data-hide-selected	Hide selected options from the dropdown (multiple mode)	boolean	false
data-max-items	Maximum number of selections (multiple mode)	number	Infinity
data-size	Component size: sm, md, lg	string	md
data-dir	Text direction: ltr, rtl, auto	string	auto
data-locale	Locale identifier for i18n strings	string	en
data-open-on-focus	Open dropdown when the element receives focus	boolean	true
data-disabled	Disable the select programmatically	boolean	false
data-loading	Show loading indicator	boolean	false
data-dropdown-parent	CSS selector for the dropdown's parent container	string	null
data-dropdown-position	Dropdown position: auto, top, bottom	string	auto
data-dropdown-class	Additional CSS class(es) for the dropdown	string	""
data-wrapper-class	Additional CSS class(es) for the wrapper	string	""

AJAX

Attribute	Description	Type	Default
data-ajax-url	URL to fetch options from (supports tokens)	string	—
data-ajax-method	HTTP method for the request	string	GET
data-ajax-delay	Debounce delay in milliseconds	number	300
data-ajax-min-chars	Minimum characters before triggering AJAX search	number	1
data-ajax-data-key	Dot-notation path to the results array in the response	string	data
data-ajax-cache	Cache AJAX responses	boolean	true
data-ajax-headers	JSON string of custom HTTP headers	string	"{}"
data-ajax-resolve-url	URL to resolve pre-selected IDs to full objects	string	—
data-selected	Comma-separated values to pre-select (used with AJAX)	string	—

Field Mapping

Attribute	Description	Type	Default
data-option-id	Field name in AJAX response for the option value	string	id
data-option-text	Field name in AJAX response for the option label	string	text
data-option-disabled	Field name for disabled state	string	disabled
data-option-group	Field name for option grouping	string	group

Templates

Attribute	Description	Type	Default
data-template-option	HTML template for dropdown options	string	—
data-template-item	HTML template for selected items	string	—
data-template-no-results	HTML template when no results are found	string	—
data-template-loading	HTML template for loading state	string	—

TIP

Templates use the {@field_name} token syntax. Any field from the option data can be referenced. For AJAX options, this includes all fields returned by the API.

Pagination

Attribute	Description	Type	Default
data-pagination	Enable infinite-scroll pagination	boolean	false
data-pagination-limit	Number of results per page	number	20
data-pagination-more-key	Dot-notation path to the "has more" flag in the response	string	pagination.more

Chaining

Attribute	Description	Type	Default
data-chain-group	Name identifying the chain group	string	—
data-chained-index	Position in the chain (0-based)	number	—
data-chained-child-data	JSON mapping of parent values to child options	string	—
data-chained-child-ajax-data	AJAX URL template for child options (uses {@val} for parent value)	string	—
data-chained-disabled-on-empty	Disable when parent has no value	boolean	true
data-chained-clear-on-parent-change	Clear value when parent changes	boolean	true
data-chained-skip-empty	Skip this level if no options are available	boolean	false

Plugins

Attribute	Description	Type	Default
data-plugins	Comma-separated list of plugin names to activate	string	""

Tagging

Attribute	Description	Type	Default
data-create-items	Allow users to create new options	boolean	false
data-create-items-text	Text for the "Add" prompt (supports {@term})	string	Add "{@term}"
data-create-items-pattern	Regex pattern for validating new values	string	—
data-tags-separator	Separator character for the tags plugin	string	,

Text Overrides

These attributes override locale strings for a specific element.

Attribute	Description	Type	Default
data-no-results-text	Text shown when no options match	string	Locale default
data-searching-text	Text shown during AJAX search	string	Locale default
data-load-more-text	Text for the "load more" pagination trigger	string	Locale default
data-input-too-short-text	Text shown when input is below min-chars	string	Locale default

Miscellaneous

Attribute	Description	Type	Default
data-tab-index	Custom tabindex for the control	number	0
data-form-name	Override the name attribute for form submission	string	Element's name
data-copy-classes-to-dropdown	Copy the select element's classes to the dropdown	boolean	false
data-render-option-content-as-html	Render option template content as HTML (not escaped)	boolean	false
data-render-item-content-as-html	Render item template content as HTML (not escaped)	boolean	false

WARNING

Setting data-render-option-content-as-html or data-render-item-content-as-html to true can expose your application to XSS attacks if the data is user-generated. Only enable this when you trust the source of the data.