Getting Started

Start using Vanilla Smart Select in your project in just a few minutes. This guide will take you from installation to your first functional dropdown.

Installation

Vanilla Smart Select can be installed in several ways, depending on your project setup:

Via NPM

Recommended for modern projects with build tools (Webpack, Vite, Rollup, etc.):

npm install vanilla-smart-select

Or using Yarn:

yarn add vanilla-smart-select

Via CDN

Perfect for rapid prototyping or projects without a build process:

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vanilla-smart-select@1.0.1/dist/vanilla-smart-select.min.css">

<!-- JavaScript -->
<script src="https://cdn.jsdelivr.net/npm/vanilla-smart-select@1.0.1/dist/vanilla-smart-select.min.js"></script>

💡 Tip: For production, we recommend pinning a specific version: https://unpkg.com/vanilla-smart-select@1.0.1/dist/...

Direct Download

You can also download the files directly from the GitHub repository:

Visit the releases page
Download the latest version
Extract the files from the dist/ folder
Include the CSS and JS files in your project

Basic Usage

1. Include the Files

First, include the CSS in the <head> and JavaScript before closing <body>:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="vanilla-smart-select.min.css">
</head>
<body>
  <!-- Your content here -->

  <script src="vanilla-smart-select.min.js"></script>
</body>
</html>

2. Create the Select Element

Create a standard HTML <select> element:

<select id="my-select">
  <option value="">Select an option</option>
  <option value="1">JavaScript</option>
  <option value="2">Python</option>
  <option value="3">Java</option>
  <option value="4">C++</option>
  <option value="5">Ruby</option>
</select>

3. Initialize the Plugin

Use JavaScript to transform the select:

// Wait for DOM to load
document.addEventListener('DOMContentLoaded', function() {
  // Initialize Vanilla Smart Select
  const select = new VanillaSmartSelect('#my-select', {
    placeholder: 'Choose a language...',
    searchable: true,
    allowClear: true
  });
});

Live Example

Programming Languages:

ES Modules

For projects using ES Modules (Webpack, Vite, etc.):

// Import the plugin and styles
import VanillaSmartSelect from 'vanilla-smart-select';
import 'vanilla-smart-select/dist/vanilla-smart-select.min.css';

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

CommonJS (Node.js)

For Node.js environments or bundlers using CommonJS:

// Import using require
const VanillaSmartSelect = require('vanilla-smart-select');

// Import CSS (in supported environments)
require('vanilla-smart-select/dist/vanilla-smart-select.min.css');

Common Options

Here are some of the most commonly used configuration options:

Option	Type	Default	Description
`placeholder`	String	`''`	Text displayed when nothing is selected
`searchable`	Boolean	`true`	Enables option search
`allowClear`	Boolean	`false`	Shows button to clear selection
`multiple`	Boolean	`false`	Allows multiple selection
`disabled`	Boolean	`false`	Disables the select
`closeOnSelect`	Boolean	`true`	Closes dropdown after selecting

See the complete configuration documentation for all available options (40+).

Quick Examples

Multiple Selection

const multiSelect = new VanillaSmartSelect('#multi-select', {
  multiple: true,
  placeholder: 'Select multiple items...',
  closeOnSelect: false
});

Frameworks (multi-select):

With Option Groups

<select id="grouped-select">
  <optgroup label="Frontend">
    <option value="react">React</option>
    <option value="vue">Vue.js</option>
  </optgroup>
  <optgroup label="Backend">
    <option value="node">Node.js</option>
    <option value="django">Django</option>
  </optgroup>
</select>

Technologies (grouped):

With HTML5 Validation

<form>
  <select id="required-select" required>
    <option value="">Select...</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </select>
  <button type="submit">Submit</button>
</form>

Working with Values

Get Selected Value

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

// For multi-select
const values = multiSelect.val();
console.log(values); // ["1", "2", "3"]

Set Value Programmatically

// Single select
select.val('2');

// Multi-select
multiSelect.val(['1', '3', '5']);

Clear Selection

select.clear();

Get Complete Data

// Returns complete object with id, text, etc.
const selected = select.getSelected();
console.log(selected);
// { id: "1", text: "JavaScript", element: {...} }

Listening to Events

You can listen to various events emitted by the plugin:

const select = new VanillaSmartSelect('#my-select');

// When an item is selected
select.on('vs:select', function(e) {
  console.log('Item selected:', e.detail);
});

// When value changes
select.on('vs:change', function(e) {
  console.log('Value changed:', this.val());
});

// When dropdown opens
select.on('vs:open', function(e) {
  console.log('Dropdown opened');
});

// When a search is performed
select.on('vs:query', function(e) {
  console.log('Searching:', e.detail.query);
});

See all available events in the events documentation.

Destroying Instance

To completely remove the plugin and restore the original select:

// Destroy and clean up event listeners
select.destroy();

// Now the element returns to being a native select

Next Steps

💡

Explore Examples

10+ interactive examples showing advanced features

📖

API Reference

Complete documentation of all available methods

⚙️

Configuration

All 40+ configuration options explained

🎨

Custom Templates

Learn to create results with rich HTML

🌐

AJAX & Remote Data

Load data from external APIs dynamically

⚡

Events

Complete system of events and callbacks

Troubleshooting

The select is not being transformed

Check if CSS and JS files were loaded correctly
Make sure JavaScript code executes after DOM loads
Check browser console for errors
Confirm CSS selector is correct

Styles don't appear correctly

Check if CSS was included before JavaScript
Look for conflicts with other CSS frameworks
Inspect elements in DevTools to check applied classes

Conflicts with Bootstrap/other frameworks

Vanilla Smart Select uses the .vs- prefix in all classes to avoid conflicts
See the Bootstrap integration documentation for details

💬 Need help? Open an issue on GitHub or consult the complete documentation.