Introdução

O componente ToggleGroup é um conjunto de botões de alternância projetados para seleção única ou múltipla. É amplamente usado para permitir que os usuários escolham estilos de layout mutuamente exclusivos (p. ex. alternadores de visualização Grade vs. Lista) ou agrupem modificadores inclusivos (p. ex. botões de formatação de texto para Negrito, Itálico e Sublinhado).

O ToggleGroup está totalmente integrado como um bloco toggleGroup no Page Builder, permitindo que editores de conteúdo e desenvolvedores configurem facilmente opções visuais, comportamentos de múltipla seleção e paletas de cores ativas diretamente no CMS.

Uso

Estes exemplos ilustram como os editores de conteúdo vinculam e estruturam botões de alternância interativos.

1. Barra de formatação de texto de múltipla seleção

Permite que vários itens sejam pressionados e ativos ao mesmo tempo. Excelente para interruptores de recursos de múltipla seleção ou painéis de edição de texto.

{
  "type": "toggleGroup",
  "multiple": true,
  "defaultValue": ["bold"],
  "items": [
    { "label": "B", "value": "bold" },
    { "label": "I", "value": "italic" },
    { "label": "U", "value": "underline" }
  ],
  "interactive": true
}

2. Alternador de layout de seleção única (tema roxo)

Demonstra o modo de seleção única, onde apenas um item pode estar ativo por vez. As escolhas ativas são estilizadas com tokens de tema roxo acentuado personalizado.

{
  "type": "toggleGroup",
  "multiple": false,
  "defaultValue": ["list"],
  "items": [
    { "label": "Grid View", "value": "grid" },
    { "label": "List View", "value": "list" }
  ],
  "colorPalette": "purple",
  "interactive": true
}

3. Grupo de navegação vertical compacto

Organiza as opções de alternância verticalmente em vez de horizontalmente, com uma escala de tamanho compacta.

{
  "type": "toggleGroup",
  "orientation": "vertical",
  "defaultValue": ["dashboard"],
  "items": [
    { "label": "Dashboard", "value": "dashboard" },
    { "label": "Settings", "value": "settings" }
  ],
  "size": "sm",
  "interactive": true
}

Propriedades

Esquema dos itens do grupo de alternância

Cada entrada dentro do array items aceita os seguintes parâmetros:

Notas para desenvolvedores e acessibilidade

• Padrões de acessibilidade WAI-ARIA: Renderiza uma barra de ferramentas robusta navegável por teclado:
  • O contêiner raiz recebe role="group".
  • Itens individuais são renderizados como role="checkbox" com estados aria-checked quando multiple é true, ou como role="radio" com estados aria-checked caso contrário.
• Navegação por teclado com foco móvel (Roving Focus): Suporta movimento de foco nativo:
  • As teclas de seta (Direita/Baixo para avançar, Esquerda/Cima para retroceder) percorrem automaticamente o foco entre os botões ativos, seguindo o eixo orientation escolhido.
  • As teclas Home e End pulam o foco instantaneamente para o primeiro e o último botão ativado do grupo.
• Associação de formulário: As opções de alternância atualizam perfeitamente o contexto de estado associado, permitindo que contêineres pai ou hooks de formulário capturem as mudanças dinamicamente.