Data Attributes Reference

A complete alphabetical reference of all HTML data attributes supported by DotSelect.

Quick Reference

Attribute	Description	Values / Type	Default
data-ajax-cache	Cache AJAX responses to avoid duplicate requests	boolean	true
data-ajax-data-key	Dot-notation path to the results array in JSON response	string	data
data-ajax-delay	Debounce delay (ms) before sending AJAX request	number	300
data-ajax-headers	JSON-encoded custom HTTP headers for AJAX requests	string (JSON)	"{}"
data-ajax-method	HTTP method for AJAX requests	GET, POST	GET
data-ajax-min-chars	Minimum characters typed before triggering AJAX search	number	1
data-ajax-resolve-url	URL to resolve pre-selected AJAX values to full objects	string (URL)	—
data-ajax-url	URL template for fetching options (supports tokens)	string (URL)	—
data-allow-clear	Show a clear button to reset the selection	boolean	false
data-chain-group	Name linking selects into a chained group	string	—
data-chained-child-ajax-data	AJAX URL template for loading child options based on parent	string (URL)	—
data-chained-child-data	JSON map of parent values to static child option arrays	string (JSON)	—
data-chained-clear-on-parent-change	Clear this select when its parent value changes	boolean	true
data-chained-disabled-on-empty	Disable this select when the parent has no value	boolean	true
data-chained-index	Zero-based position of this select in its chain group	number	—
data-chained-skip-empty	Skip this chain level if no options are available	boolean	false
data-close-on-select	Close the dropdown after a selection is made	boolean	true (single) / false (multi)
data-copy-classes-to-dropdown	Copy the original element's CSS classes to the dropdown	boolean	false
data-create-items	Allow users to create new options by typing	boolean	false
data-create-items-pattern	Regex pattern to validate user-created values	string (regex)	—
data-create-items-text	Prompt text for creating new items (supports {@term})	string	Add "{@term}"
data-dir	Text direction for the component	ltr, rtl, auto	auto
data-disabled	Programmatically disable the select	boolean	false
data-dot-select	Enable DotSelect on this element (required)	flag	—
data-dropdown-class	Additional CSS class(es) applied to the dropdown	string	""
data-dropdown-parent	CSS selector for the element the dropdown is appended to	string (selector)	null
data-dropdown-position	Force dropdown position	auto, top, bottom	auto
data-form-name	Override the form submission name attribute	string	element's name
data-hide-selected	Hide already-selected options from the dropdown	boolean	false
data-input-too-short-text	Override locale string for min-chars message	string	locale default
data-load-more-text	Override locale string for pagination trigger	string	locale default
data-loading	Show the loading indicator	boolean	false
data-locale	Locale identifier for UI strings	string	en
data-max-items	Maximum number of items that can be selected (multiple mode)	number	Infinity
data-no-results-text	Override locale string for "no results" message	string	locale default
data-open-on-focus	Open the dropdown when the element receives focus	boolean	true
data-option-disabled	AJAX response field name for option disabled state	string	disabled
data-option-group	AJAX response field name for option grouping	string	group
data-option-id	AJAX response field name for option value	string	id
data-option-text	AJAX response field name for option display text	string	text
data-pagination	Enable infinite-scroll pagination for AJAX	boolean	false
data-pagination-limit	Number of results per page	number	20
data-pagination-more-key	Dot-notation path to "has more" flag in response	string	pagination.more
data-placeholder	Placeholder text when no option is selected	string	""
data-plugins	Comma-separated list of plugins to activate	string	""
data-render-item-content-as-html	Render item template content as unescaped HTML	boolean	false
data-render-option-content-as-html	Render option template content as unescaped HTML	boolean	false
data-searchable	Enable the search/filter input	boolean	false
data-searching-text	Override locale string for "searching" message	string	locale default
data-selected	Comma-separated values to pre-select (for AJAX mode)	string	—
data-size	Component size variant	sm, md, lg	md
data-tab-index	Custom tabindex for the control	number	0
data-tags-separator	Separator character for the tags plugin	string	,
data-template-item	HTML template for rendering selected items	string (HTML)	—
data-template-loading	HTML template for the loading state	string (HTML)	—
data-template-no-results	HTML template for the "no results" state	string (HTML)	—
data-template-option	HTML template for rendering dropdown options	string (HTML)	—
data-wrapper-class	Additional CSS class(es) applied to the wrapper element	string	""

Boolean Attributes

Boolean attributes accept "true" or "false" as string values:

<!-- Enable -->
<select data-dot-select data-searchable="true">

<!-- Disable (same as omitting) -->
<select data-dot-select data-searchable="false">

TIP

The presence of a boolean attribute without a value is treated as "true":

<!-- These are equivalent -->
<select data-dot-select data-searchable="true">
<select data-dot-select data-searchable>

Token Syntax in Attributes

Several attributes support token replacement using the {@token} syntax:

Token	Available In	Description
{@term}	AJAX URLs, templates	Current search query
{@page}	AJAX URLs	Current pagination page number
{@selected}	AJAX URLs	Comma-separated currently selected values
{@val}	Chained AJAX URLs	Parent select's current value
{@pagination_limit}	AJAX URLs	Configured results per page
{@count}	Text overrides	Numeric value (e.g., min-chars count)
{@field_name}	Templates	Any field from option data