MeSwitch

Toggle switch para ativar/desativar estados binários. Suporta dois tamanhos, label integrado via prop e submissão em formulários nativos.

Playground

Importação

Vue 3

<script setup>
import { MeSwitch } from '@me/ui-vue3'
</script>

Vue 2

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

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

Uso Básico

<script setup>
import { ref } from 'vue'
const isActive = ref(false)
</script>

<template>
  <MeSwitch v-model="isActive" />
</template>

Tamanhos

O MeSwitch possui dois tamanhos.

Standard (padrão)

<MeSwitch v-model="isActive" size="standard" />

Small

<MeSwitch v-model="isActive" size="small" />

Disabled

O switch desabilitado permanece visível e focalizável para usuários de teclado — o estado é comunicado via aria-disabled em vez do atributo disabled nativo.

<MeSwitch v-model="isActive" disabled />

Com Label

O MeSwitch utiliza o componente MeLabel para renderizar o label. Use a prop label para o caso simples — se precisar definir outras props do MeLabel (como mandatory ou tooltip), use label-props. Consulte a documentação do MeLabel para ver todas as opções disponíveis.

Caso simples

NotificaçõesModo escuro

<MeSwitch v-model="notificacoes" label="Notificações" />
<MeSwitch v-model="modoEscuro" size="small" label="Modo escuro" />

Com props adicionais do MeLabel

Para obrigatoriedade, tooltip ou qualquer outra prop do MeLabel, use label-props.

Receber e-mails*Notificações push

help_outline

Envia alertas em tempo real

<MeSwitch v-model="emails" label="Receber e-mails" :label-props="{ mandatory: true }" />

<MeSwitch
  v-model="push"
  label="Notificações push"
  :label-props="{ tooltip: 'Envia alertas em tempo real' }"
/>

Posição do label

Use label-position para controlar onde o label aparece em relação ao switch. O padrão é right.

Direita (padrão)EsquerdaAcimaAbaixo

<MeSwitch v-model="ativo" label="Direita (padrão)" label-position="right" />
<MeSwitch v-model="ativo" label="Esquerda" label-position="left" />
<MeSwitch v-model="ativo" label="Acima" label-position="top" />
<MeSwitch v-model="ativo" label="Abaixo" label-position="bottom" />

Sem label visível

Quando não houver label, use aria-label para leitores de tela:

<MeSwitch v-model="darkMode" aria-label="Ativar modo escuro" />

Em Formulários Nativos

Use a prop name para participar de submissões nativas com <form>. Um <input type="checkbox"> oculto é incluído automaticamente.

Receber e-mails

<form @submit.prevent="enviar">
  <MeSwitch v-model="notificacoes" name="notificacoes" label="Receber e-mails" />
</form>

Comparação de Tamanhos

<MeSwitch :model-value="true" size="standard" />
<MeSwitch :model-value="true" size="small" />

API

Props

Prop	Tipo	Padrão	Descrição
modelValue	boolean	undefined	Valor controlado pelo v-model (Vue 3).
value	boolean	undefined	Valor controlado pelo v-model (Vue 2, retrocompatibilidade).
size	'standard' | 'small'	'standard'	Tamanho do switch.
disabled	boolean	false	Desabilita a interação. Usa aria-disabled — o elemento permanece focalizável.
name	string	undefined	Nome para submissão em <form> nativo. Inclui um <input type="checkbox"> oculto.
label	string	undefined	Texto do label exibido junto ao switch.
labelProps	Omit<MeLabelProps, 'label'>	undefined	Props extras repassadas ao MeLabel (ex: mandatory, tooltip).
labelPosition	Position	'right'	Posição do label em relação ao switch. Valores: top, right, bottom, left (e demais valores de Position).

Atributos HTML (via $attrs)

Qualquer atributo HTML passado ao componente é aplicado diretamente no <button> raiz:

Atributo	Exemplo	Descrição
id	id="meu-switch"	Vincula com <label for="">.
aria-label	aria-label="Ativar"	Label para leitores de tela quando não há label visível.
aria-labelledby	aria-labelledby="id-do-label"	Aponta para um elemento externo como label.

Eventos

Evento	Payload	Descrição
update:modelValue	boolean	Emitido ao alternar o estado (Vue 3 v-model).
change	boolean	Emitido ao alternar o estado. Evento semântico correto para toggle — use @change para reagir a interações.

Acessibilidade

• role="switch" — leitores de tela anunciam o elemento como toggle switch
• aria-checked="true/false" — reflete automaticamente o estado atual
• aria-disabled="true" — comunica estado desabilitado sem remover o elemento do tab order
• tabindex="0" — o switch sempre permanece focalizável, inclusive quando desabilitado
• label — texto renderizado via MeLabel, lido como parte do contexto do campo
• id + <label for=""> — vínculo nativo entre label externo e switch
• :focus-visible com outline visível para navegação por teclado
• name — inclui <input> oculto para compatibilidade com <form> nativo

Sempre forneça um label

Use a prop label, um <label for=""> externo ou aria-label. Switches sem identificação são inacessíveis para usuários de leitores de tela.

Disabled vs aria-disabled

Ao contrário do atributo disabled nativo (que remove o elemento do tab order), o MeSwitch usa aria-disabled. Isso garante que usuários de teclado e leitores de tela consigam perceber e anunciar o switch mesmo quando desabilitado.