Grupos de botões

Os grupos de botões organizam os botões e adicionam interações entre eles aplicando mudanças coordenadas de forma, movimento e largura aos botões e botões de ícone. Há duas variantes de grupos de botões:

  1. Grupo de botões padrão: adiciona interação entre botões adjacentes para que eles respondam uns aos outros quando pressionados.
  2. Grupo de botões conectados: agrupa botões ativar/desativar para que os usuários selecionem opções, alternem visualizações ou classifiquem elementos em uma página.
Grupos de botões padrão à esquerda e grupos de botões conectados à direita.
Figura 1. Grupos de botões padrão (1, à esquerda) e grupos de botões conectados (2, à direita).

Como usar grupos de botões

  • Aplica a transformação de forma quando os botões são pressionados ou selecionados.
  • Os grupos de botões conectados substituem os botões segmentados.
  • Funciona com todos os tamanhos de botão: extrapequeno (XS), pequeno (S), médio (M), grande (L) e extragrande (XL).
  • Oferece suporte a padrões de seleção única, seleção múltipla e seleção obrigatória.
Grupos de botões com botões de vários formatos e tamanhos.
Figura 2. Grupos de botões com botões de vários formatos e tamanhos.

Grupo de botões padrão

Use o elemento de composição ButtonGroup para colocar botões em uma sequência horizontal que expande o item pressionado, comprime os itens vizinhos e move os itens extras para um menu flutuante quando o espaço é limitado. Os grupos de botões precisam ficar em uma única linha, em vez de serem divididos em uma segunda linha.

O snippet a seguir demonstra como implementar um grupo de botões padrão com um indicador de menu flutuante:

@Composable
fun ButtonGroupSample() {
    val numButtons = 10
    ButtonGroup(
        overflowIndicator = { menuState ->
            ButtonGroupDefaults.OverflowIndicator(menuState = menuState)
        }
    ) {
        for (i in 0 until numButtons) {
            clickableItem(onClick = {}, label = "$i")
        }
    }
}

Grupo de botões conectados

Use grupos de botões conectados para padrões de seleção única ou múltipla criados com elementos combináveis ToggleButton e formas conectadas ButtonGroupDefaults.

Comportamento do grupo de botões conectados.
Figura 3. Comportamento responsivo do grupo de botões conectados.

Única seleção

Use um grupo de botões conectados de seleção única quando o usuário escolher uma opção de um conjunto mutuamente exclusivo. O snippet a seguir implementa um grupo de botões conectados de seleção única usando ToggleButton e Role.RadioButton:

@Composable
fun SingleSelectConnectedButtonGroupSample() {
    val options = listOf("Work", "Restaurant", "Coffee", "Search", "Home")
    val unCheckedIcons =
        listOf(
            AppIcons.Work,
            AppIcons.Restaurant,
            AppIcons.Coffee,
            AppIcons.Search,
            AppIcons.Home,
        )
    val checkedIcons =
        listOf(
            AppIcons.WorkFilled,
            AppIcons.Restaurant,
            AppIcons.CoffeeFilled,
            AppIcons.Search,
            AppIcons.HomeFilled,
        )
    var selectedIndex by remember { mutableIntStateOf(0) }

    FlexBox(
        modifier = Modifier.padding(horizontal = 8.dp).fillMaxWidth(),
        config = {
            direction(FlexDirection.Row)
            wrap(FlexWrap.Wrap)
            columnGap(ButtonGroupDefaults.ConnectedSpaceBetween)
            rowGap(2.dp)
        },
    ) {
        options.forEachIndexed { index, label ->
            ToggleButton(
                checked = selectedIndex == index,
                onCheckedChange = { selectedIndex = index },
                shapes =
                    when (index) {
                        0 -> ButtonGroupDefaults.connectedLeadingButtonShapes()
                        options.lastIndex -> ButtonGroupDefaults.connectedTrailingButtonShapes()
                        else -> ButtonGroupDefaults.connectedMiddleButtonShapes()
                    },
                modifier = Modifier.semantics { role = Role.RadioButton },
            ) {
                Icon(
                    painter =
                        rememberVectorPainter(
                            if (selectedIndex == index) checkedIcons[index] else unCheckedIcons[index]
                        ),
                    contentDescription = null,
                )
                Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing))
                Text(label)
            }
        }
    }
}

Seleção múltipla

Use um grupo de botões conectados de seleção múltipla quando o usuário puder alternar entre zero ou mais opções de forma independente. O snippet abaixo implementa um grupo de botões conectados de seleção múltipla usando ToggleButton e mutableStateListOf:

@Composable
fun MultiSelectConnectedButtonGroupSample() {
    val options = listOf("Work", "Restaurant", "Coffee", "Search", "Home")
    val unCheckedIcons =
        listOf(
            AppIcons.Work,
            AppIcons.Restaurant,
            AppIcons.Coffee,
            AppIcons.Search,
            AppIcons.Home,
        )
    val checkedIcons =
        listOf(
            AppIcons.WorkFilled,
            AppIcons.Restaurant,
            AppIcons.CoffeeFilled,
            AppIcons.Search,
            AppIcons.HomeFilled,
        )
    val checked = remember { mutableStateListOf(false, false, false, false, false) }

    FlexBox(
        modifier = Modifier.padding(horizontal = 8.dp).fillMaxWidth(),
        config = {
            direction(FlexDirection.Row)
            wrap(FlexWrap.Wrap)
            columnGap(ButtonGroupDefaults.ConnectedSpaceBetween)
            rowGap(2.dp)
        },
    ) {
        options.forEachIndexed { index, label ->
            ToggleButton(
                checked = checked[index],
                onCheckedChange = { checked[index] = it },
                shapes =
                    when (index) {
                        0 -> ButtonGroupDefaults.connectedLeadingButtonShapes()
                        options.lastIndex -> ButtonGroupDefaults.connectedTrailingButtonShapes()
                        else -> ButtonGroupDefaults.connectedMiddleButtonShapes()
                    },
            ) {
                Icon(
                    painter =
                        rememberVectorPainter(
                            if (checked[index]) checkedIcons[index] else unCheckedIcons[index]
                        ),
                    contentDescription = null,
                )
                Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing))
                Text(label)
            }
        }
    }
}