API Reference

Initialization

Creates a new instance of Vanilla Smart Select.

const select = new VanillaSmartSelect('#my-select', {
  placeholder: 'Select...',
  searchable: true
});

Value Management

val([value])

Gets or sets the selected value.

// Get value
const value = select.val(); // "1"

// Set value (single)
select.val('2');

// Set values (multiple)
select.val(['1', '3', '5']);

// Returns null if nothing is selected

getSelected()

Returns the complete object of selected items.

const selected = select.getSelected();
// Single: { id: "1", text: "Option 1", element: HTMLElement, ... }
// Multiple: [{ id: "1", ... }, { id: "2", ... }]

clear()

Clears the entire selection.

select.clear();

Item Selection

select(id)

Selects a specific item by ID.

select.select('3'); // Selects the item with value="3"

unselect(id)

Removes the selection of an item (multi-select only).

select.unselect('3'); // Removes item with value="3"

Data Management

data([newData])

Gets or replaces all data/options.

// Get current data
const currentData = select.data();

// Replace all data
select.data([
  { id: '1', text: 'New Item 1' },
  { id: '2', text: 'New Item 2' },
  { id: '3', text: 'New Item 3', disabled: true }
]);

addOption(option)

Adds a new option to the select.

select.addOption({
  id: '99',
  text: 'New Option',
  selected: false,
  disabled: false
});

removeOption(id)

Removes an option by ID.

select.removeOption('99');

Dropdown Control

open()

Opens the dropdown.

select.open();

close()

Closes the dropdown.

select.close();

toggle()

Toggles between open and closed.

select.toggle();

isOpen()

Checks if the dropdown is open.

if (select.isOpen()) {
  console.log('Dropdown is open');
}

State and Control

enable()

Enables the select.

select.enable();

disable()

Disables the select.

select.disable();

focus()

Sets focus on the select.

select.focus();

destroy()

Destroys the instance and restores the original select.

select.destroy(); // Completely removes the plugin

Validation

checkValidity()

Checks if the element is valid according to HTML5 rules.

const isValid = select.checkValidity(); // true/false

reportValidity()

Shows validation message if invalid.

select.reportValidity(); // Shows message to user

setCustomValidity(message)

Sets a custom error message.

select.setCustomValidity('Please select a valid option');

validationMessage()

Gets the current validation message.

const message = select.validationMessage();

willValidate()

Checks if the element participates in validation.

const willValidate = select.willValidate(); // true/false

Internationalization

updateLanguage(language)

Updates language messages dynamically.

select.updateLanguage({
  noResults: 'No results found',
  searching: 'Searching...',
  searchPlaceholder: 'Type to search...'
  // ... other messages
});

See more at Internationalization.

Events

on(event, handler)

Adds an event listener.

select.on('vs:select', function(e) {
  console.log('Item selected:', e.detail);
});

select.on('vs:change', function() {
  console.log('Value changed to:', this.val());
});

off(event, handler)

Removes an event listener.

function myHandler(e) {
  console.log(e);
}

select.on('vs:select', myHandler);
select.off('vs:select', myHandler); // Removes the listener

See all available events at Events.

Properties

Complete Example

// Create instance
const select = new VanillaSmartSelect('#my-select', {
  placeholder: 'Select...',
  searchable: true,
  allowClear: true
});

// Set initial value
select.val('2');

// Add event
select.on('vs:change', function() {
  console.log('New value:', this.val());
  console.log('Selected item:', this.getSelected());
});

// Add new option
select.addOption({
  id: '99',
  text: 'Extra Option'
});

// Open programmatically
select.open();

// Clear after 5 seconds
setTimeout(() => {
  select.clear();
  select.close();
}, 5000);

// Destroy when no longer needed
// select.destroy();