API Reference

Inicialização

Cria uma nova instância do Vanilla Smart Select.

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

Gerenciamento de Valores

val([value])

Obtém ou define o valor selecionado.

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

// Definir valor (single)
select.val('2');

// Definir valores (multiple)
select.val(['1', '3', '5']);

// Retorna null se nada estiver selecionado

getSelected()

Retorna o objeto completo dos itens selecionados.

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

clear()

Limpa toda a seleção.

select.clear();

Seleção de Itens

select(id)

Seleciona um item específico pelo ID.

select.select('3'); // Seleciona o item com value="3"

unselect(id)

Remove a seleção de um item (apenas multi-select).

select.unselect('3'); // Remove item com value="3"

Gerenciamento de Dados

data([newData])

Obtém ou substitui todos os dados/opções.

// Obter dados atuais
const currentData = select.data();

// Substituir todos os dados
select.data([
  { id: '1', text: 'Novo Item 1' },
  { id: '2', text: 'Novo Item 2' },
  { id: '3', text: 'Novo Item 3', disabled: true }
]);

addOption(option)

Adiciona uma nova opção ao select.

select.addOption({
  id: '99',
  text: 'Nova Opção',
  selected: false,
  disabled: false
});

removeOption(id)

Remove uma opção pelo ID.

select.removeOption('99');

Controle do Dropdown

open()

Abre o dropdown.

select.open();

close()

Fecha o dropdown.

select.close();

toggle()

Alterna entre aberto e fechado.

select.toggle();

isOpen()

Verifica se o dropdown está aberto.

if (select.isOpen()) {
  console.log('Dropdown está aberto');
}

Estado e Controle

enable()

Habilita o select.

select.enable();

disable()

Desabilita o select.

select.disable();

focus()

Define o foco no select.

select.focus();

destroy()

Destrói a instância e restaura o select original.

select.destroy(); // Remove completamente o plugin

Validação

checkValidity()

Verifica se o elemento é válido segundo as regras HTML5.

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

reportValidity()

Mostra mensagem de validação se inválido.

select.reportValidity(); // Mostra mensagem ao usuário

setCustomValidity(message)

Define uma mensagem de erro customizada.

select.setCustomValidity('Por favor selecione uma opção válida');

validationMessage()

Obtém a mensagem de validação atual.

const message = select.validationMessage();

willValidate()

Verifica se o elemento participa da validação.

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

Internacionalização

updateLanguage(language)

Atualiza as mensagens de idioma dinamicamente.

select.updateLanguage({
  noResults: 'Nenhum resultado encontrado',
  searching: 'Buscando...',
  searchPlaceholder: 'Digite para buscar...'
  // ... outras mensagens
});

Veja mais em Internacionalização.

Eventos

on(event, handler)

Adiciona um listener de evento.

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

select.on('vs:change', function() {
  console.log('Valor mudou para:', this.val());
});

off(event, handler)

Remove um listener de evento.

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

select.on('vs:select', myHandler);
select.off('vs:select', myHandler); // Remove o listener

Veja todos os eventos disponíveis em Eventos.

Propriedades

Exemplo Completo

// Criar instância
const select = new VanillaSmartSelect('#my-select', {
  placeholder: 'Selecione...',
  searchable: true,
  allowClear: true
});

// Definir valor inicial
select.val('2');

// Adicionar evento
select.on('vs:change', function() {
  console.log('Novo valor:', this.val());
  console.log('Item selecionado:', this.getSelected());
});

// Adicionar nova opção
select.addOption({
  id: '99',
  text: 'Opção Extra'
});

// Abrir programaticamente
select.open();

// Limpar após 5 segundos
setTimeout(() => {
  select.clear();
  select.close();
}, 5000);

// Destruir quando não precisar mais
// select.destroy();