Configuration Options

Complete reference for all 40+ available configuration options.

Display Options

Option	Type	Default	Description
`placeholder`	String	`''`	Text displayed when nothing is selected
`theme`	String	`'default'`	CSS theme name to apply
`width`	String	`'resolve'`	Element width ('100%', '300px', 'resolve', 'element')
`containerCssClass`	String	`''`	Additional CSS classes for the container
`dropdownCssClass`	String	`''`	Additional CSS classes for the dropdown

new VanillaSmartSelect('#select', {
  placeholder: 'Choose an option...',
  theme: 'bootstrap',
  width: '100%',
  containerCssClass: 'my-custom-class'
});

Behavior Options

Option	Type	Default	Description
`multiple`	Boolean	`false`	Enables multiple selection
`searchable`	Boolean	`true`	Enables search field
`allowClear`	Boolean	`false`	Shows button to clear selection
`disabled`	Boolean	`false`	Initial disabled state
`closeOnSelect`	Boolean	`true`	Closes dropdown after selecting (false in multi)

Search Options

Option	Type	Default	Description
`searchMinimumLength`	Number	`0`	Minimum characters to start search
`searchDelay`	Number	`250`	Debounce delay for search (ms)
`matchStrategy`	String	`'contains'`	Search strategy: 'startsWith', 'contains', 'exact'
`matcher`	Function	`null`	Custom search function

new VanillaSmartSelect('#select', {
  searchMinimumLength: 2,
  searchDelay: 300,
  matchStrategy: 'startsWith',
  matcher: function(params, data) {
    // Custom search logic
    if (data.text.toLowerCase().indexOf(params.term.toLowerCase()) > -1) {
      return data;
    }
    return null;
  }
});

Templates

Option	Type	Default	Description
`templateResult`	Function	`null`	Template to render results in dropdown
`templateSelection`	Function	`null`	Template to render selected item
`escapeMarkup`	Function	`(markup) => markup`	Function to escape HTML (return string or null)

new VanillaSmartSelect('#select', {
  templateResult: function(item) {
    if (!item.id) return item.text;
    return `
      
        
        ${item.text}
      
    `;
  },
  templateSelection: function(item) {
    return `${item.text}`;
  }
});

See more at Custom Templates.

AJAX & Remote Data

Option	Type	Description
`ajax.url`	String \| Function	API URL or function that returns the URL
`ajax.method`	String	HTTP method (GET, POST, etc.)
`ajax.delay`	Number	Debounce delay (default: 250ms)
`ajax.data`	Function	Function that returns request parameters
`ajax.processResults`	Function	Processes API response
`ajax.cache`	Boolean	Enables request caching (default: true)

new VanillaSmartSelect('#select', {
  ajax: {
    url: 'https://api.example.com/search',
    method: 'GET',
    delay: 300,
    data: function(params) {
      return {
        q: params.term, // Search term
        page: params.page || 1
      };
    },
    processResults: function(data, params) {
      return {
        results: data.items,
        pagination: {
          more: data.hasMore
        }
      };
    }
  }
});

See more at AJAX & Remote Data.

Tagging (Dynamic Creation)

Option	Type	Default	Description
`tags`	Boolean	`false`	Allows creating new options
`createTag`	Function	`null`	Function to create new item
`insertTag`	Function	`null`	Where to insert the new tag in the list

new VanillaSmartSelect('#select', {
  tags: true,
  createTag: function(params) {
    const term = params.term.trim();
    if (term === '') return null;
    return {
      id: term,
      text: term,
      newTag: true
    };
  }
});

Selection Limit

Option	Type	Default	Description
`maximumSelectionLength`	Number	`0`	Maximum number of selections (0 = unlimited)

new VanillaSmartSelect('#select', {
  multiple: true,
  maximumSelectionLength: 5,
  language: {
    maximumSelected: function(args) {
      return `Maximum of ${args.maximum} items allowed`;
    }
  }
});

Internationalization

Option	Type	Default	Description
`language`	Object \| String	`'auto'`	Language object or code ('en', 'pt-BR', 'es', 'auto')

See all customizable messages at Internationalization.

Accessibility

Option	Type	Default	Description
`ariaLabel`	String	`null`	Custom aria-label attribute
`ariaDescribedBy`	String	`null`	ID of element describing the select

Callbacks

Option	Type	Description
`onOpen`	Function	Called when dropdown opens
`onClose`	Function	Called when dropdown closes
`onChange`	Function	Called when value changes
`onSelect`	Function	Called when an item is selected
`onUnselect`	Function	Called when an item is deselected
`onClear`	Function	Called when selection is cleared

new VanillaSmartSelect('#select', {
  onChange: function() {
    console.log('Value changed:', this.val());
  },
  onSelect: function(e) {
    console.log('Item selected:', e.detail);
  }
});

Note: Callbacks are equivalent to events. Use select.on() for more flexibility.

Complete Example

const select = new VanillaSmartSelect('#my-select', {
  // Display
  placeholder: 'Choose an option...',
  width: '100%',
  theme: 'default',

  // Behavior
  searchable: true,
  multiple: false,
  allowClear: true,
  closeOnSelect: true,

  // Search
  searchMinimumLength: 0,
  searchDelay: 250,
  matchStrategy: 'contains',

  // Templates
  templateResult: function(item) {
    return item.text;
  },

  // Language
  language: 'pt-BR',

  // Callbacks
  onChange: function() {
    console.log('Changed to:', this.val());
  }
});