Methods

DotSelect provides a rich JavaScript API for programmatic control. Methods are available on DotSelect instances, as static methods on the DotSelect class, and on chain objects.

Getting an Instance

// Create a new instance
const select = new DotSelect(document.querySelector('#my-select'));

// Or get an existing instance
const select = DotSelect.getInstance(document.querySelector('#my-select'));

Instance Methods

setValue(value)

Set the current value. Accepts a string (single) or an array of strings (multiple).

// Single select
select.setValue('us');

// Multiple select
select.setValue(['js', 'py', 'go']);

Parameters:

Name	Type	Description
`value`	`string \| string[]`	The value(s) to select

Returns: DotSelect — the instance (chainable)

getValue()

Get the current value.

// Single select
const value = select.getValue(); // "us"

// Multiple select
const values = select.getValue(); // ["js", "py", "go"]

Returns: string | string[]

getData()

Get the full data objects for the currently selected option(s).

const data = select.getData();
// Single: { id: "us", text: "United States" }
// Multiple: [{ id: "js", text: "JavaScript" }, { id: "py", text: "Python" }]

Returns: object | object[]

clear()

Clear the current selection.

select.clear();

Returns: DotSelect

enable()

Enable the select (remove disabled state).

select.enable();

Returns: DotSelect

disable()

Disable the select.

select.disable();

Returns: DotSelect

open()

Open the dropdown programmatically.

select.open();

Returns: DotSelect

close()

Close the dropdown programmatically.

select.close();

Returns: DotSelect

addOption(data, selected)

Add a new option to the select.

select.addOption({ id: 'new', text: 'New Option' });

// Add and select it immediately
select.addOption({ id: 'new', text: 'New Option' }, true);

Parameters:

Name	Type	Description
`data`	`object`	Option data with at least `id` and `text`
`selected`	`boolean`	Whether to select the new option (default: `false`)

Returns: DotSelect

removeOption(value)

Remove an option by its value.

select.removeOption('old-value');

Parameters:

Name	Type	Description
`value`	`string`	The value of the option to remove

Returns: DotSelect

clearOptions()

Remove all options from the select.

select.clearOptions();

Returns: DotSelect

reload()

Reload options from the AJAX source. Useful when external data has changed.

select.reload();

Returns: DotSelect

refresh()

Re-render the component without reloading data. Useful after DOM changes.

select.refresh();

Returns: DotSelect

updateSettings(settings)

Update configuration settings at runtime.

select.updateSettings({
  placeholder: 'New placeholder...',
  searchable: true,
  maxItems: 5,
});

Parameters:

Name	Type	Description
`settings`	`object`	Key-value pairs of settings to update

Returns: DotSelect

WARNING

Not all settings can be changed at runtime. Structural settings like ajax-url require calling reload() after updating.

hide()

Hide the entire DotSelect component.

select.hide();

Returns: DotSelect

show()

Show a previously hidden DotSelect component.

select.show();

Returns: DotSelect

destroy()

Remove DotSelect enhancements and restore the original <select> element.

select.destroy();

getElement()

Get the original <select> DOM element.

const el = select.getElement();
// <select data-dot-select ...>

Returns: HTMLSelectElement

getWrapper()

Get the DotSelect wrapper DOM element.

const wrapper = select.getWrapper();
// <div class="dot-select ...">

Returns: HTMLElement

getSettings()

Get the current resolved settings object.

const settings = select.getSettings();
console.log(settings.placeholder); // "Choose..."
console.log(settings.searchable);  // true

Returns: object

getOptionCount()

Get the total number of options currently in the select.

const count = select.getOptionCount();

Returns: number

isOpen()

Check whether the dropdown is currently open.

if (select.isOpen()) {
  select.close();
}

Returns: boolean

isHidden()

Check whether the component is currently hidden.

if (select.isHidden()) {
  select.show();
}

Returns: boolean

Static Methods

DotSelect.init(root?)

Initialize all <select data-dot-select> elements. Optionally limit to a subtree.

// Initialize all
DotSelect.init();

// Initialize within a container
DotSelect.init(document.querySelector('#form-container'));

Parameters:

Name	Type	Description
`root`	`HTMLElement`	Optional root element to search within (default: `document`)

DotSelect.chain(groupName)

Get or create a chain controller for the named group.

const chain = DotSelect.chain('location');

Parameters:

Name	Type	Description
`groupName`	`string`	The chain group name (matches `data-chain-group`)

Returns: ChainController

DotSelect.getInstance(element)

Get the DotSelect instance associated with a DOM element, or null if not initialized.

const instance = DotSelect.getInstance(document.querySelector('#my-select'));

Parameters:

Name	Type	Description
`element`	`HTMLSelectElement`	The original select element

Returns: DotSelect | null

DotSelect.destroyAll()

Destroy all DotSelect instances on the page, restoring original select elements.

DotSelect.destroyAll();

DotSelect.plugin(name, factory)

DotSelect.plugin('my-plugin', (instance, options) => {
  return {
    init() { /* called on initialization */ },
    destroy() { /* called on destroy */ },
    onOpen() { /* called when dropdown opens */ },
  };
});

Parameters:

Name	Type	Description
`name`	`string`	Plugin identifier (used in `data-plugins`)
`factory`	`function`	Factory function receiving `(instance, options)`

Chain API

The chain controller returned by DotSelect.chain() provides these methods:

chain.getValues()

Get all current values across the chain as an object keyed by index.

const chain = DotSelect.chain('location');
const values = chain.getValues();
// { 0: "us", 1: "ca", 2: "sf" }

Returns: object

chain.getValue(index)

Get the value at a specific index in the chain.

const state = chain.getValue(1); // "ca"

Parameters:

Name	Type	Description
`index`	`number`	The chain index

Returns: string | null

chain.onChange(callback)

chain.onChange((index, value, instance) => {
  console.log(`Level ${index} changed to "${value}"`);
});

Parameters:

Name	Type	Description
`callback`	`function`	Receives `(index: number, value: string, instance: DotSelect)`

Returns: ChainController

chain.whenReady(callback)

chain.whenReady(() => {
  console.log('Chain is fully ready');
});

Parameters:

Name	Type	Description
`callback`	`function`	Called when all members are initialized

Returns: ChainController

chain.getMembers()

Get all DotSelect instances in the chain, ordered by index.

const members = chain.getMembers();
// [DotSelect (index 0), DotSelect (index 1), DotSelect (index 2)]

Returns: DotSelect[]

chain.destroy()

Destroy the chain controller and unlink all members (does not destroy individual instances).

chain.destroy();

Methods ​

Getting an Instance ​

Instance Methods ​

setValue(value) ​

getValue() ​

getData() ​

clear() ​

enable() ​

disable() ​

open() ​

close() ​

addOption(data, selected) ​

removeOption(value) ​

clearOptions() ​

reload() ​

refresh() ​

updateSettings(settings) ​

hide() ​

show() ​

destroy() ​

getElement() ​

getWrapper() ​

getSettings() ​

getOptionCount() ​

isOpen() ​

isHidden() ​

Static Methods ​

DotSelect.init(root?) ​

DotSelect.chain(groupName) ​

DotSelect.getInstance(element) ​

DotSelect.destroyAll() ​

DotSelect.plugin(name, factory) ​

Chain API ​

chain.getValues() ​

chain.getValue(index) ​

chain.onChange(callback) ​

chain.whenReady(callback) ​

chain.getMembers() ​

chain.destroy() ​

Methods

Getting an Instance

Instance Methods

setValue(value)

getValue()

getData()

clear()

enable()

disable()

open()

close()

addOption(data, selected)

removeOption(value)

clearOptions()

reload()

refresh()

updateSettings(settings)

hide()

show()

destroy()

getElement()

getWrapper()

getSettings()

getOptionCount()

isOpen()

isHidden()

Static Methods

DotSelect.init(root?)

DotSelect.chain(groupName)

DotSelect.getInstance(element)

DotSelect.destroyAll()

DotSelect.plugin(name, factory)

Chain API

chain.getValues()

chain.getValue(index)

chain.onChange(callback)

chain.whenReady(callback)

chain.getMembers()

chain.destroy()