MeAutocomplete

Campo de busca com autocomplete assíncrono. Suporta dois modos: searchFn (componente gerencia debounce e loading) e controlado (pai fornece :options e :loading). O texto digitado persiste ao fechar o dropdown — padrão Combobox.

Playground

Importação

Vue 3

<script setup>
import { MeAutocomplete } from '@me/ui-vue3'
import type { AutocompleteOption } from '@me/ui-vue3'
</script>

Vue 2

<script>
import { MeAutocomplete } from '@me/ui-vue2'

export default {
  components: { MeAutocomplete }
}
</script>

Uso Básico — Modo searchFn

Dados de exemplo

Nos demos abaixo, digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

Passe uma função assíncrona via :search-fn. O componente gerencia debounce (padrão 800 ms) e exibe o spinner de loading automaticamente.

CNPJ da empresa

<script setup>
import { ref } from 'vue'
import { MeAutocomplete } from '@me/ui-vue3'
import type { AutocompleteOption } from '@me/ui-vue3'

const cnpj = ref(null)

async function buscarEmpresas(term: string): Promise<AutocompleteOption[]> {
  const { data } = await api.get('/company/search', { params: { term } })
  return data.map((c) => ({
    label: `${c.cnpj} - ${c.name}`,
    value: c.cnpj,
    data: c,
  }))
}
</script>

<template>
  <MeAutocomplete
    v-model="cnpj"
    :search-fn="buscarEmpresas"
    label="CNPJ da empresa"
    placeholder="Digite o CNPJ ou nome"
  />
</template>

Modo Controlado

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

O pai é responsável por buscar e atualizar :options. O componente emite @search quando o usuário digita um termo válido.

Buscar empresa

<script setup>
import { ref } from 'vue'
import { MeAutocomplete } from '@me/ui-vue3'
import type { AutocompleteOption } from '@me/ui-vue3'

const value   = ref(null)
const options = ref<AutocompleteOption[]>([])
const loading = ref(false)

async function handleSearch(term: string) {
  if (!term) { options.value = []; return }
  loading.value = true
  const { data } = await api.get('/search', { params: { term } })
  options.value = data.map((item) => ({ label: item.name, value: item.id }))
  loading.value = false
}
</script>

<template>
  <MeAutocomplete
    v-model="value"
    :options="options"
    :loading="loading"
    label="Buscar empresa"
    @search="handleSearch"
  />
</template>

Com Label e Obrigatório

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

Use label para exibir um rótulo e :mandatory="true" para adicionar o asterisco de campo obrigatório.

CNPJ da empresa*

<MeAutocomplete
  v-model="value"
  :search-fn="buscar"
  label="CNPJ da empresa"
  :mandatory="true"
/>

Validação de mínimo de caracteres

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

Quando minChars é definido, o componente exibe automaticamente uma mensagem de erro enquanto o usuário digita menos que o mínimo — sem nenhuma prop extra.

Buscar empresa

<MeAutocomplete
  v-model="value"
  :search-fn="buscar"
  label="Buscar empresa"
  :min-chars="4"
/>
<!-- Digitar 1–3 chars exibe automaticamente: "É preciso no mínimo 4 caracteres." -->

Com Mensagem de Erro

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

Use error-message para exibir um erro customizado. Ele tem prioridade sobre a mensagem automática de minChars.

CNPJ

CNPJ inválido ou não encontrado

<MeAutocomplete
  v-model="value"
  :search-fn="buscar"
  label="CNPJ"
  error-message="CNPJ inválido ou não encontrado"
/>

Máscara

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados por nome, ou comece com dígitos para testar a máscara.

Use a prop mask para formatar o input automaticamente. O padrão é uma string onde X representa um dígito e os demais caracteres são separadores literais inseridos automaticamente.

A máscara só é aplicada quando o usuário digita apenas dígitos — ao digitar letras (ex: busca por nome de empresa), o campo funciona livremente.

CNPJ

CPF

<!-- CNPJ -->
<MeAutocomplete
  v-model="cnpj"
  :search-fn="buscar"
  label="CNPJ"
  mask="XX.XXX.XXX/XXXX-XX"
  :min-chars="4"
/>

<!-- CPF -->
<MeAutocomplete
  v-model="cpf"
  :search-fn="buscar"
  label="CPF"
  mask="XXX.XXX.XXX-XX"
  :min-chars="4"
/>

Variante Visual

Use variant para controlar o comportamento de foco do campo.

• light (padrão): foco destacado com sombra ocean (teal) no wrapper.
• dark: foco destacado com sombra escura (neutra) no wrapper — sem a cor verde/teal.

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

light (padrão)

dark

<!-- light (padrão) — sombra no wrapper ao focar -->
<MeAutocomplete v-model="value" :search-fn="buscar" variant="light" />

<!-- dark — foco via focus-visible no input -->
<MeAutocomplete v-model="value" :search-fn="buscar" variant="dark" />

Disabled

Campo desabilitado

<MeAutocomplete
  v-model="value"
  :search-fn="buscar"
  label="Campo desabilitado"
  :disabled="true"
/>

Sem botão de limpar

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

Sem botão de limpar

<MeAutocomplete
  v-model="value"
  :search-fn="buscar"
  :clearable="false"
/>

Eventos

Dados de exemplo

Digite Alpha, Beta ou Gamma (ou apenas Empresa) para ver resultados.

Empresa

Último evento: Nenhum

<script setup>
import { ref } from 'vue'

const value     = ref(null)
const lastEvent = ref('Nenhum')
</script>

<template>
  <MeAutocomplete
    v-model="value"
    :search-fn="buscar"
    label="Empresa"
    @select="(opt) => lastEvent = opt ? `select: ${opt.label}` : 'select: null'"
    @clear="lastEvent = 'clear'"
    @focus="lastEvent = 'focus'"
    @blur="lastEvent = 'blur'"
  />
  <p>Último evento: <strong>{{ lastEvent }}</strong></p>
</template>

API

Props

Prop	Tipo	Padrão	Descrição
modelValue	string | number | null	null	Valor selecionado — use com v-model
searchFn	(term: string) => Promise<AutocompleteOption[]>	—	Modo searchFn: função de busca assíncrona. O componente gerencia debounce e loading.
debounce	number	800	Delay do debounce em ms. Apenas no modo searchFn.
options	AutocompleteOption[]	[]	Modo controlado: opções fornecidas pelo pai.
loading	boolean	false	Modo controlado: estado de loading externo.
label	string	—	Texto do label exibido acima do campo.
placeholder	string	'Buscar...'	Placeholder do input.
disabled	boolean	false	Desabilita o campo.
mandatory	boolean	false	Exibe asterisco de obrigatório no label.
minChars	number	3	Mínimo de caracteres para disparar a busca. Enquanto abaixo do mínimo, exibe automaticamente "É preciso no mínimo N caracteres."
errorMessage	string	—	Mensagem de erro customizada. Tem prioridade sobre a mensagem automática de minChars.
noResultsText	string	'Nenhum resultado encontrado'	Texto exibido no dropdown quando não há resultados.
clearable	boolean	true	Exibe botão para limpar o campo.
variant	'light' | 'dark'	'light'	Variante visual do foco. light: sombra ocean (teal) no wrapper. dark: sombra escura no wrapper, sem a cor verde/teal.
mask	string	—	Padrão de máscara aplicado quando o usuário digita apenas dígitos. Use X para cada dígito e outros chars como separadores literais. Ex: 'XX.XXX.XXX/XXXX-XX' (CNPJ), 'XXX.XXX.XXX-XX' (CPF).

Tipo AutocompleteOption

type AutocompleteOption<D = unknown> = {
  label: string          // Texto exibido no dropdown e no input após seleção
  value: string | number // Valor emitido no v-model ao selecionar
  data?: D               // Payload arbitrário acessível no evento @select
  disabled?: boolean
}

Eventos

Evento	Payload	Descrição
update:modelValue	string | number | null	Emitido ao selecionar ou limpar — use com v-model
search	string	Modo controlado: emitido quando o usuário digita um termo válido
select	AutocompleteOption | null	Emitido ao selecionar uma opção ou ao limpar
clear	—	Emitido ao clicar no botão de limpar
focus	—	Emitido ao focar no input
blur	—	Emitido ao perder o foco
open	—	Emitido ao abrir o dropdown
close	—	Emitido ao fechar o dropdown

Acessibilidade

• O input possui role="combobox" e aria-haspopup="listbox"
• aria-expanded reflete o estado do dropdown
• Cada opção possui role="option" com aria-selected e aria-disabled
• Opções desabilitadas têm aria-disabled="true"

Navegação por Teclado

Tecla	Ação
ArrowDown	Move o foco para a próxima opção (pula desabilitadas)
ArrowUp	Move o foco para a opção anterior (pula desabilitadas)
Enter	Seleciona a opção com foco
Escape	Fecha o dropdown mantendo o texto digitado
Tab	Fecha o dropdown e avança o foco normalmente

Posicionamento inteligente

O MeAutocomplete detecta automaticamente o espaço disponível na viewport e abre o dropdown para cima quando não há espaço suficiente abaixo.