Limite de Seleção

O recurso de limite de seleção permite controlar o número máximo de itens que podem ser selecionados em selects múltiplos. É útil para cenários onde você deseja limitar a quantidade de escolhas do usuário.

Limite de 3 Itens

Neste exemplo, o usuário pode selecionar no máximo 3 habilidades. Após atingir o limite, não será possível adicionar mais itens até que algum seja removido.

<label for="skills">Selecione até 3 habilidades:</label>
<select id="skills" multiple>
  <option value="javascript">JavaScript</option>
  <option value="python">Python</option>
  <option value="java">Java</option>
  <option value="csharp">C#</option>
  <option value="php">PHP</option>
  <option value="ruby">Ruby</option>
  <option value="go">Go</option>
  <option value="rust">Rust</option>
  <option value="swift">Swift</option>
  <option value="kotlin">Kotlin</option>
</select>

new VanillaSmartSelectClass('#skills', {
  searchable: true,
  maximumSelectionLength: 3
});

Limite de 2 Itens

Exemplo com limite mais restritivo de apenas 2 frameworks. Útil quando você quer forçar o usuário a escolher suas principais preferências.

<label for="frameworks">Selecione até 2 frameworks:</label>
<select id="frameworks" multiple>
  <option value="react">React</option>
  <option value="vue">Vue.js</option>
  <option value="angular">Angular</option>
  <option value="svelte">Svelte</option>
  <option value="ember">Ember.js</option>
  <option value="backbone">Backbone.js</option>
</select>

new VanillaSmartSelectClass('#frameworks', {
  searchable: true,
  maximumSelectionLength: 2
});

Limite de 5 Itens com Grupos

O limite de seleção funciona perfeitamente com optgroups. Neste exemplo, você pode selecionar até 5 países de diferentes continentes.

<label for="countries">Selecione até 5 países:</label>
<select id="countries" multiple>
  <optgroup label="América do Sul">
    <option value="br">Brasil</option>
    <option value="ar">Argentina</option>
    <option value="cl">Chile</option>
    <option value="co">Colômbia</option>
    <option value="pe">Peru</option>
  </optgroup>
  <optgroup label="Europa">
    <option value="pt">Portugal</option>
    <option value="es">Espanha</option>
    <option value="fr">França</option>
    <option value="it">Itália</option>
    <option value="de">Alemanha</option>
  </optgroup>
  <optgroup label="Ásia">
    <option value="jp">Japão</option>
    <option value="cn">China</option>
    <option value="kr">Coreia do Sul</option>
    <option value="in">Índia</option>
  </optgroup>
</select>

new VanillaSmartSelectClass('#countries', {
  searchable: true,
  maximumSelectionLength: 5
});

Sem Limite (Padrão)

Por padrão, não há limite de seleção. Você pode definir explicitamente maximumSelectionLength: 0 ou simplesmente omitir a configuração para permitir seleção ilimitada.

<label for="colors">Selecione quantas cores desejar:</label>
<select id="colors" multiple>
  <option value="red">Vermelho</option>
  <option value="blue">Azul</option>
  <option value="green">Verde</option>
  <option value="yellow">Amarelo</option>
  <option value="purple">Roxo</option>
  <option value="orange">Laranja</option>
  <option value="pink">Rosa</option>
  <option value="brown">Marrom</option>
  <option value="black">Preto</option>
  <option value="white">Branco</option>
</select>

new VanillaSmartSelectClass('#colors', {
  searchable: true,
  maximumSelectionLength: 0  // 0 = unlimited (default)
});

Monitorando Eventos de Limite

Você pode escutar o evento vs:selectionLimitReached para executar ações personalizadas quando o limite é atingido. O evento fornece detalhes sobre o limite máximo e a mensagem exibida.

<label for="tags">Selecione até 4 tags:</label>
<select id="tags" multiple>
  <option value="tag1">Design</option>
  <option value="tag2">Desenvolvimento</option>
  <option value="tag3">Marketing</option>
  <option value="tag4">Vendas</option>
  <option value="tag5">Suporte</option>
  <option value="tag6">Administração</option>
  <option value="tag7">Recursos Humanos</option>
  <option value="tag8">Financeiro</option>
</select>

<div id="event-log"></div>

const tagsElement = document.getElementById('tags');
const eventLog = document.getElementById('event-log');

new VanillaSmartSelectClass('#tags', {
  searchable: true,
  maximumSelectionLength: 4
});

// Listen to selection limit reached event
tagsElement.addEventListener('vs:selectionLimitReached', (e) => {
  const timestamp = new Date().toLocaleTimeString();
  const logEntry = document.createElement('div');
  logEntry.style.marginBottom = '8px';
  logEntry.innerHTML = `
    <strong style="color: #856404;">[${timestamp}] Limite Atingido!</strong><br>
    <span style="color: #666;">Máximo: ${e.detail.maximum} | Mensagem: "${e.detail.message}"</span>
  `;
  eventLog.insertBefore(logEntry, eventLog.firstChild);
});

// Also log select events
tagsElement.addEventListener('vs:select', (e) => {
  const timestamp = new Date().toLocaleTimeString();
  const logEntry = document.createElement('div');
  logEntry.style.marginBottom = '8px';
  logEntry.innerHTML = `
    <strong style="color: #28a745;">[${timestamp}] Selecionado:</strong>
    <span style="color: #666;">${e.detail.data.text}</span>
  `;
  eventLog.insertBefore(logEntry, eventLog.firstChild);
});

Configuração da API

Configurações disponíveis para controle do limite de seleção:

Eventos Relacionados

Eventos disparados durante o controle de limite de seleção:

Personalização de Mensagens (i18n)

Você pode personalizar a mensagem exibida quando o limite é atingido através das configurações de internacionalização:

new VanillaSmartSelectClass('#element', {
  maximumSelectionLength: 3,
  language: {
    maximumSelected: function(args) {
      return 'Você só pode selecionar ' + args.maximum + ' itens';
    }
  }
});

// Ou usando texto simples
new VanillaSmartSelectClass('#element', {
  maximumSelectionLength: 5,
  language: {
    maximumSelected: 'Limite de 5 itens atingido!'
  }
});

Casos de Uso Comuns

Boas Práticas