Opções de Configuração

Referência completa de todas as 40+ opções de configuração disponíveis.

Opções de Display

Opção	Tipo	Padrão	Descrição
`placeholder`	String	`''`	Texto exibido quando nada está selecionado
`theme`	String	`'default'`	Nome do tema CSS a ser aplicado
`width`	String	`'resolve'`	Largura do elemento ('100%', '300px', 'resolve', 'element')
`containerCssClass`	String	`''`	Classes CSS adicionais para o container
`dropdownCssClass`	String	`''`	Classes CSS adicionais para o dropdown

new VanillaSmartSelect('#select', {
  placeholder: 'Escolha uma opção...',
  theme: 'bootstrap',
  width: '100%',
  containerCssClass: 'my-custom-class'
});

Opções de Comportamento

Opção	Tipo	Padrão	Descrição
`multiple`	Boolean	`false`	Habilita seleção múltipla
`searchable`	Boolean	`true`	Habilita campo de busca
`allowClear`	Boolean	`false`	Mostra botão para limpar seleção
`disabled`	Boolean	`false`	Estado inicial desabilitado
`closeOnSelect`	Boolean	`true`	Fecha dropdown após selecionar (false em multi)

Opções de Busca

Opção	Tipo	Padrão	Descrição
`searchMinimumLength`	Number	`0`	Mínimo de caracteres para iniciar busca
`searchDelay`	Number	`250`	Delay de debounce para busca (ms)
`matchStrategy`	String	`'contains'`	Estratégia de busca: 'startsWith', 'contains', 'exact'
`matcher`	Function	`null`	Função customizada de busca

new VanillaSmartSelect('#select', {
  searchMinimumLength: 2,
  searchDelay: 300,
  matchStrategy: 'startsWith',
  matcher: function(params, data) {
    // Lógica customizada de busca
    if (data.text.toLowerCase().indexOf(params.term.toLowerCase()) > -1) {
      return data;
    }
    return null;
  }
});

Templates

Opção	Tipo	Padrão	Descrição
`templateResult`	Function	`null`	Template para renderizar resultados no dropdown
`templateSelection`	Function	`null`	Template para renderizar item selecionado
`escapeMarkup`	Function	`(markup) => markup`	Função para escapar HTML (retorne string ou null)

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

Veja mais em Templates Customizados.

AJAX & Dados Remotos

Opção	Tipo	Descrição
`ajax.url`	String \| Function	URL da API ou função que retorna a URL
`ajax.method`	String	Método HTTP (GET, POST, etc.)
`ajax.delay`	Number	Delay de debounce (padrão: 250ms)
`ajax.data`	Function	Função que retorna parâmetros da requisição
`ajax.processResults`	Function	Processa resposta da API
`ajax.cache`	Boolean	Habilita cache de requisições (padrão: true)

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

Veja mais em AJAX & Dados Remotos.

Tagging (Criação Dinâmica)

Opção	Tipo	Padrão	Descrição
`tags`	Boolean	`false`	Permite criar novas opções
`createTag`	Function	`null`	Função para criar novo item
`insertTag`	Function	`null`	Onde inserir a nova tag na lista

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

Limite de Seleção

Opção	Tipo	Padrão	Descrição
`maximumSelectionLength`	Number	`0`	Número máximo de seleções (0 = ilimitado)

new VanillaSmartSelect('#select', {
  multiple: true,
  maximumSelectionLength: 5,
  language: {
    maximumSelected: function(args) {
      return `Máximo de ${args.maximum} itens permitidos`;
    }
  }
});

Internacionalização

Opção	Tipo	Padrão	Descrição
`language`	Object \| String	`'auto'`	Objeto de idioma ou código ('en', 'pt-BR', 'es', 'auto')

Veja todas as mensagens customizáveis em Internacionalização.

Acessibilidade

Opção	Tipo	Padrão	Descrição
`ariaLabel`	String	`null`	Atributo aria-label customizado
`ariaDescribedBy`	String	`null`	ID do elemento que descreve o select

Callbacks

Opção	Tipo	Descrição
`onOpen`	Function	Chamado quando o dropdown abre
`onClose`	Function	Chamado quando o dropdown fecha
`onChange`	Function	Chamado quando o valor muda
`onSelect`	Function	Chamado quando um item é selecionado
`onUnselect`	Function	Chamado quando um item é desselecionado
`onClear`	Function	Chamado quando a seleção é limpa

new VanillaSmartSelect('#select', {
  onChange: function() {
    console.log('Valor mudou:', this.val());
  },
  onSelect: function(e) {
    console.log('Item selecionado:', e.detail);
  }
});

Nota: Callbacks são equivalentes a eventos. Use select.on() para maior flexibilidade.

Exemplo Completo

const select = new VanillaSmartSelect('#my-select', {
  // Display
  placeholder: 'Escolha uma opção...',
  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());
  }
});