Botão

Os botões são componentes fundamentais que permitem ao usuário acionar uma ação definida. Há cinco tipos de botões. Esta tabela descreve a aparência de cada um dos cinco tipos de botão, bem como onde eles devem ser usados:

Tipo Aparência Finalidade
Sólido Fundo sólido com texto contrastante. Botões de prioridade alta. Eles são usados para ações principais em um aplicativo, como "enviar" e "salvar". O efeito de sombra destaca a importância do botão.
Sólido tonal A cor do plano de fundo varia para combinar com a superfície. Também para ações principais ou significativas. Os botões tonais preenchidos oferecem mais peso visual e são adequados para funções como "Adicionar ao carrinho" e "Fazer login".
Elevada Destaca-se por ter uma sombra. Tem uma finalidade semelhante à dos botões tonais. Aumente a elevação para que o botão apareça com ainda mais destaque.
Delineado Tem uma borda sem preenchimento. Botões de prioridade média, que contêm ações importantes, mas não principais. Eles combinam bem com outros botões para indicar ações alternativas e secundárias, como "Cancelar" ou "Voltar".
Texto Mostra o texto sem plano de fundo ou borda. Botões de baixa ênfase, ideais para ações menos críticas, como links de navegação, ou funções secundárias, como "Saiba mais" ou "Ver detalhes".

Esta imagem mostra os cinco tipos de botões no Material Design:

Um exemplo de cada um dos cinco componentes de botão, com as características exclusivas destacadas.
Figura 1. Os cinco componentes de botão.

Superfície da API

  • onClick: a função que o sistema chama quando o usuário pressiona o botão.
  • enabled: quando false, esse parâmetro faz com que o botão apareça como indisponível e inativo.
  • colors: uma instância de ButtonColors que determina as cores usadas no botão.
  • contentPadding: o padding dentro do botão.

Botão preenchido

O componente de botão preenchido usa o elemento combinável básico Button. Por padrão, ele é preenchido com uma cor sólida. O snippet mostra como implementar o componente e visualizá-lo de forma interativa:

@Composable
fun FilledButtonExample(onClick: () -> Unit) {
    Button(onClick = { onClick() }) {
        Text("Filled")
    }
}

Botão tonal preenchido

O componente de botão tonal preenchido usa o elemento combinável FilledTonalButton. Por padrão, ele é preenchido com uma cor tonal.

O snippet mostra como implementar o componente e visualizá-lo de forma interativa:

@Composable
fun FilledTonalButtonExample(onClick: () -> Unit) {
    FilledTonalButton(onClick = { onClick() }) {
        Text("Tonal")
    }
}

Botão com contorno

O componente de botão com contorno usa o elemento combinável OutlinedButton. Ele aparece com um contorno por padrão.

O snippet mostra como implementar o componente e visualizá-lo de forma interativa:

@Composable
fun OutlinedButtonExample(onClick: () -> Unit) {
    OutlinedButton(onClick = { onClick() }) {
        Text("Outlined")
    }
}

Botão elevado

O componente de botão elevado usa o elemento combinável ElevatedButton. Ele tem uma sombra que representa o efeito de elevação por padrão. É um botão preenchido que inclui uma sombra.

O snippet mostra como implementar o componente e visualizá-lo de forma interativa:

@Composable
fun ElevatedButtonExample(onClick: () -> Unit) {
    ElevatedButton(onClick = { onClick() }) {
        Text("Elevated")
    }
}

Botão de texto

O componente de botão de texto usa o elemento combinável TextButton. Ele aparece apenas como texto até ser pressionado. Por padrão, ele não tem preenchimento sólido nem contorno.

O snippet mostra como implementar o componente e visualizá-lo de forma interativa:

@Composable
fun TextButtonExample(onClick: () -> Unit) {
    TextButton(
        onClick = { onClick() }
    ) {
        Text("Text Button")
    }
}

Atualização do M3 Expressive

Agora os botões têm uma variedade maior de formas, tamanhos e funcionalidades de alternância, além de poderem mudar de forma quando selecionados.

Tamanhos e formas do botão
Figura 7. Variações de tamanho e forma do botão do Material 3 Expressive.

Para mais informações sobre as atualizações do M3 Expressive para botões, consulte as diretrizes de botões do Material Design 3.

Botões ativar

Há quatro estilos de botão ativar/desativar disponíveis: preenchido, elevado, tonal e delineado.

Sólido

O estilo de botão preenchido tem o maior impacto visual depois do botão de ação flutuante (FAB, na sigla em inglês) e precisa ser usado para ações importantes e finais que concluem um fluxo, como Salvar, Participar agora ou Confirmar.

O snippet a seguir demonstra como implementar um botão ativar/desativar preenchido:

@Composable
fun ToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    ToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Button")
    }
}

Elevada

Os botões elevados se separam de um plano de fundo visualmente proeminente.

O snippet a seguir demonstra como implementar um botão ativar/desativar elevado:

@Composable
fun ElevatedToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    ElevatedToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Elevated Button")
    }
}

Tonal

O estilo de botão tonal é preenchido com uma cor tonal por padrão. Ele é útil em contextos em que um botão de prioridade mais baixa requer um pouco mais de ênfase do que um contorno daria.

O snippet a seguir demonstra como implementar um botão ativar/desativar tonal usando FilledTonalToggleButton:

@Composable
fun TonalToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    FilledTonalToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Tonal Button")
    }
}

Delineado

O estilo com contorno é ideal para botões de prioridade média que contêm ações importantes, mas que não são as principais em um produto.

O snippet abaixo demonstra como implementar um botão ativar/desativar com contorno:

@Composable
fun OutlinedToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    OutlinedToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Text("Outlined Button")
    }
}

Opções de tamanho

O Material 3 Expressive adiciona quatro opções de tamanho além do tamanho pequeno padrão: extrapequeno, médio, grande e extragrande. As sobrecargas de botões expressivos usam um parâmetro shapes obrigatório, ou você pode aplicar o dimensionamento expressivo a um Button padrão definindo ButtonDefaults.contentPaddingFor(...), como mostram os exemplos a seguir:

Pequeno (padrão atual)

Medidas de botões pequenos:

  • Altura: 40 dp

Botão padrão

O snippet abaixo demonstra como implementar um botão pequeno com um ícone:

@Composable
fun ButtonWithIconSample() {
    Button(
        onClick = { /* Do something! */ },
        contentPadding = ButtonDefaults.contentPaddingFor(ButtonDefaults.MinHeight, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.FavoriteFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(ButtonDefaults.MinHeight)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(ButtonDefaults.MinHeight)))
        Text("Like")
    }
}

Botão ativar/desativar

O snippet a seguir demonstra como implementar um botão ativar/desativar pequeno com um ícone:

@Composable
fun ToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    ToggleButton(checked = checked, onCheckedChange = { checked = it }) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.FavoriteFilled else AppIcons.Favorite),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.IconSize),
        )
        Spacer(Modifier.size(ButtonDefaults.IconSpacing))
        Text("Like")
    }
}

Muito pequeno

Medidas do botão extra pequeno:

  • Altura: 32 dp

Botão padrão

O snippet a seguir demonstra como implementar um botão extra pequeno com um ícone:

@Composable
fun XSmallButtonWithIconSample() {
    val size = ButtonDefaults.ExtraSmallContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label")
    }
}

Botão ativar/desativar

O snippet a seguir demonstra como implementar um botão ativar/desativar extra pequeno com um ícone:

@Composable
fun XSmallToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.ExtraSmallContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label")
    }
}

Médio

Medidas do botão médio:

  • Altura: 56 dp

Botão padrão

O snippet a seguir demonstra como implementar um botão médio com um ícone:

@Composable
fun MediumButtonWithIconSample() {
    val size = ButtonDefaults.MediumContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

Botão ativar/desativar

O snippet a seguir demonstra como implementar um botão ativar/desativar médio com um ícone:

@Composable
fun MediumToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.MediumContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

Grande

Medidas de botões grandes:

  • Altura: 96 dp

Botão padrão

O snippet abaixo demonstra como implementar um botão grande com um ícone:

@Composable
fun LargeButtonWithIconSample() {
    val size = ButtonDefaults.LargeContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

Botão ativar/desativar

O snippet a seguir demonstra como implementar um botão ativar/desativar grande com um ícone:

@Composable
fun LargeToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.LargeContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

Muito grande

Medidas do botão extragrande:

  • Altura: 136 dp

Botão padrão

O snippet a seguir demonstra como implementar um botão extra grande com um ícone:

@Composable
fun XLargeButtonWithIconSample() {
    val size = ButtonDefaults.ExtraLargeContainerHeight
    Button(
        onClick = { /* Do something! */ },
        modifier = Modifier.heightIn(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size, hasStartIcon = true),
    ) {
        Icon(
            painter = rememberVectorPainter(AppIcons.EditFilled),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

Botão ativar/desativar

O snippet abaixo demonstra como implementar um botão ativar/desativar extra grande com um ícone:

@Composable
fun XLargeToggleButtonWithIconSample() {
    var checked by remember { mutableStateOf(false) }
    val size = ButtonDefaults.ExtraLargeContainerHeight
    ToggleButton(
        checked = checked,
        onCheckedChange = { checked = it },
        modifier = Modifier.heightIn(size),
        shapes = ToggleButtonDefaults.shapesFor(size),
        contentPadding = ButtonDefaults.contentPaddingFor(size),
    ) {
        Icon(
            painter = rememberVectorPainter(if (checked) AppIcons.EditFilled else AppIcons.Edit),
            contentDescription = null,
            modifier = Modifier.size(ButtonDefaults.iconSizeFor(size)),
        )
        Spacer(Modifier.size(ButtonDefaults.iconSpacingFor(size)))
        Text("Label", style = ButtonDefaults.textStyleFor(size))
    }
}

Opções de forma

Há duas opções de formato disponíveis: quadrado e redondo.

Botões quadrados mudando de tamanho.
Figura 8. Escalonamento do raio do canto do botão quadrado em vários tamanhos.

Os botões quadrados têm contêineres com cantos levemente arredondados que se ajustam de acordo com o tamanho do botão.

Exemplo de botão com cantos arredondados.
Figura 9. Botão com cantos arredondados.

Os tipos de botão redondo têm contêineres com cantos totalmente arredondados. Quando marcada, o formato de um botão ativar/desativar quadrado muda para redondo.

O snippet abaixo demonstra como implementar um botão ativar/desativar quadrado que muda de forma para redondo quando marcado:

@Composable
fun SquareToggleButtonSample() {
    var checked by remember { mutableStateOf(false) }
    val shapes =
        ToggleButtonShapes(
            shape = ToggleButtonDefaults.checkedShape,
            pressedShape = ToggleButtonDefaults.pressedShape,
            checkedShape = ToggleButtonDefaults.shape,
        )
    ToggleButton(checked = checked, onCheckedChange = { checked = it }, shapes = shapes) {
        Text("Button")
    }
}

Outros recursos