Getting Started

Comece a usar Vanilla Smart Select em seu projeto em poucos minutos. Este guia irá levá-lo da instalação até seu primeiro dropdown funcional.

Instalação

Vanilla Smart Select pode ser instalado de várias formas, dependendo da sua configuração de projeto:

Via NPM

Recomendado para projetos modernos com build tools (Webpack, Vite, Rollup, etc.):

npm install vanilla-smart-select

Ou usando Yarn:

yarn add vanilla-smart-select

Via CDN

Perfeito para prototipagem rápida ou projetos sem 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>

💡 Dica: Para produção, recomendamos fixar uma versão específica: https://unpkg.com/vanilla-smart-select@1.0.1/dist/...

Download Direto

Você também pode baixar os arquivos diretamente do repositório GitHub:

Acesse a página de releases
Baixe a versão mais recente
Extraia os arquivos da pasta dist/
Inclua os arquivos CSS e JS no seu projeto

Uso Básico

1. Incluir os Arquivos

Primeiro, inclua o CSS no <head> e o JavaScript antes do fechamento do <body>:

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="vanilla-smart-select.min.css">
</head>
<body>
  <!-- Seu conteúdo aqui -->

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

2. Criar o Elemento Select

Crie um elemento <select> HTML padrão:

<select id="my-select">
  <option value="">Selecione uma opção</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. Inicializar o Plugin

Use JavaScript para transformar o select:

// Esperar o DOM carregar
document.addEventListener('DOMContentLoaded', function() {
  // Inicializar Vanilla Smart Select
  const select = new VanillaSmartSelect('#my-select', {
    placeholder: 'Escolha uma linguagem...',
    searchable: true,
    allowClear: true
  });
});

Exemplo ao Vivo

Linguagens de Programação:

ES Modules

Para projetos que usam ES Modules (Webpack, Vite, etc.):

// Importar o plugin e estilos
import VanillaSmartSelect from 'vanilla-smart-select';
import 'vanilla-smart-select/dist/vanilla-smart-select.min.css';

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

CommonJS (Node.js)

Para ambientes Node.js ou bundlers que usam CommonJS:

// Importar usando require
const VanillaSmartSelect = require('vanilla-smart-select');

// Importar CSS (em ambientes que suportam)
require('vanilla-smart-select/dist/vanilla-smart-select.min.css');

Opções Comuns

Aqui estão algumas das opções de configuração mais usadas:

Opção	Tipo	Padrão	Descrição
`placeholder`	String	`''`	Texto exibido quando nada está selecionado
`searchable`	Boolean	`true`	Habilita a busca de opções
`allowClear`	Boolean	`false`	Mostra botão para limpar seleção
`multiple`	Boolean	`false`	Permite seleção múltipla
`disabled`	Boolean	`false`	Desabilita o select
`closeOnSelect`	Boolean	`true`	Fecha o dropdown após selecionar

Veja a documentação completa de configuração para todas as opções disponíveis (40+).

Exemplos Rápidos

Seleção Múltipla

const multiSelect = new VanillaSmartSelect('#multi-select', {
  multiple: true,
  placeholder: 'Selecione vários itens...',
  closeOnSelect: false
});

Frameworks (multi-seleção):

Com Grupos de Opções

<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>

Tecnologias (agrupadas):

Com Validação HTML5

<form>
  <select id="required-select" required>
    <option value="">Selecione...</option>
    <option value="1">Opção 1</option>
    <option value="2">Opção 2</option>
  </select>
  <button type="submit">Enviar</button>
</form>

Trabalhando com Valores

Obter Valor Selecionado

// Obter valor atual
const value = select.val();
console.log(value); // "1"

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

Definir Valor Programaticamente

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

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

Limpar Seleção

select.clear();

Obter Dados Completos

// Retorna objeto completo com id, text, etc.
const selected = select.getSelected();
console.log(selected);
// { id: "1", text: "JavaScript", element: {...} }

Ouvindo Eventos

Você pode ouvir diversos eventos emitidos pelo plugin:

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

// Quando um item é selecionado
select.on('vs:select', function(e) {
  console.log('Item selecionado:', e.detail);
});

// Quando o valor muda
select.on('vs:change', function(e) {
  console.log('Valor mudou:', this.val());
});

// Quando o dropdown abre
select.on('vs:open', function(e) {
  console.log('Dropdown aberto');
});

// Quando uma busca é realizada
select.on('vs:query', function(e) {
  console.log('Buscando:', e.detail.query);
});

Veja todos os eventos disponíveis na documentação de eventos.

Destruindo Instância

Para remover completamente o plugin e restaurar o select original:

// Destruir e limpar event listeners
select.destroy();

// Agora o elemento volta a ser um select nativo

Próximos Passos

💡

Explorar Exemplos

10+ exemplos interativos mostrando recursos avançados

📖

API Reference

Documentação completa de todos os métodos disponíveis

⚙️

Configuração

Todas as 40+ opções de configuração explicadas

🎨

Templates Customizados

Aprenda a criar resultados com HTML rico

🌐

AJAX & Dados Remotos

Carregue dados de APIs externas dinamicamente

⚡

Eventos

Sistema completo de eventos e callbacks

Solução de Problemas

O select não está sendo transformado

Verifique se os arquivos CSS e JS foram carregados corretamente
Certifique-se de que o código JavaScript está sendo executado após o DOM carregar
Verifique o console do navegador por erros
Confirme que o seletor CSS está correto

Estilos não aparecem corretamente

Verifique se o CSS foi incluído antes do JavaScript
Procure por conflitos com outros frameworks CSS
Inspecione os elementos no DevTools para verificar classes aplicadas

Conflitos com Bootstrap/outros frameworks

Vanilla Smart Select usa o prefixo .vs- em todas as classes para evitar conflitos
Veja a documentação de integração Bootstrap para detalhes

💬 Precisa de ajuda? Abra uma issue no GitHub ou consulte a documentação completa.