Los botones de ícono muestran las acciones que los usuarios pueden realizar. Los botones de ícono deben usar un ícono con un significado claro y, por lo general, representan acciones comunes o de uso frecuente.
Existen dos tipos de botones de ícono:
- Predeterminado: Estos botones pueden abrir otros elementos, como un menú o una búsqueda.
- Activar o desactivar: Estos botones pueden representar acciones binarias que se pueden activar o desactivar, como "favorito" o "marcador".
Superficie de la API
Usa el elemento componible IconButton para implementar botones de ícono estándar y IconToggleButton para un botón que alterna entre los estados seleccionado y no seleccionado. Para crear diferentes estilos visuales, como relleno, relleno tonal o contorno, usa FilledIconButton, FilledTonalIconButton y OutlinedIconButton, o sus contrapartes activables FilledIconToggleButton, FilledTonalIconToggleButton y OutlinedIconToggleButton.
Los parámetros clave para IconButton incluyen los siguientes:
onClick: Es una función lambda que se ejecuta cuando el usuario presiona el botón de ícono.enabled: Es un valor booleano que controla el estado habilitado del botón. Cuando esfalse, el botón no responde a la entrada del usuario.content: Es el contenido componible dentro del botón, por lo general, unIcon.
Los parámetros clave para IconToggleButton incluyen los siguientes:
checked: Es un valor booleano que controla el estado seleccionado del botón.onCheckedChange: Es una función lambda que se ejecuta cuando el usuario presiona el botón y proporciona el nuevo estado de marcado.enabled: Es un valor booleano que controla el estado habilitado del botón. Cuando esfalse, el botón no responde a la entrada del usuario.
Ejemplo básico: Botón de activación con ícono
Cuando un usuario activa o desactiva los botones de ícono, le permite seleccionar una opción (como agregar o quitar un elemento de favoritos), o bien anular su selección. IconToggleButton y sus variantes están diseñadas para este propósito.
En el siguiente ejemplo, se muestra cómo implementar un botón de activación con ícono que cambia su apariencia según si está seleccionado o no, administrando el estado con IconButton:
@Preview @Composable fun ToggleIconButtonExample() { // isToggled initial value should be read from a view model or persistent storage. var isToggled by rememberSaveable { mutableStateOf(false) } IconButton( onClick = { isToggled = !isToggled } ) { Icon( painter = if (isToggled) painterResource(R.drawable.favorite_filled) else painterResource(R.drawable.favorite), contentDescription = if (isToggled) "Selected icon button" else "Unselected icon button." ) } }
Puntos clave sobre el código
- El elemento
ToggleIconButtonExampleque admite composición define unIconButtonque se puede activar o desactivar.mutableStateOf(false)crea un objetoMutableStateque contiene un valor booleano, inicialmentefalse. Esto convierte aisToggleden un contenedor de estado, lo que significa que Compose recompone la IU cada vez que cambia su valor.rememberSaveablese asegura de que el estado deisToggledpersista en los cambios de configuración, como la rotación de la pantalla.
- La lambda
onClickdeIconButtondefine el comportamiento del botón cuando se hace clic en él, lo que alterna el estado entretrueyfalse. - El parámetro
painterdel elemento que admite composiciónIconcarga de forma condicional unpainterResourcediferente según el estado deisToggled. Esto cambia la apariencia visual del ícono.- Si
isToggledestrue, se carga el elemento de diseño de corazón relleno. - Si
isToggledesfalse, se carga el elemento de diseño de corazón con contorno.
- Si
- El
contentDescriptiondelIcontambién se actualiza según el estado deisToggledpara proporcionar información de accesibilidad adecuada.
Resultado
En la siguiente imagen, se muestra el botón de ícono de activación del fragmento anterior en su estado seleccionado:
Ejemplo avanzado: Acciones repetidas al presionar
En esta sección, se muestra cómo crear botones de ícono que activen una acción de forma continua mientras el usuario los mantiene presionados, en lugar de activarla solo una vez por clic.
@Composable fun MomentaryIconButton( unselectedImage: Int, selectedImage: Int, contentDescription: String, modifier: Modifier = Modifier, stepDelay: Long = 100L, // Minimum value is 1L milliseconds. onClick: () -> Unit ) { val interactionSource = remember { MutableInteractionSource() } val isPressed by interactionSource.collectIsPressedAsState() val pressedListener by rememberUpdatedState(onClick) LaunchedEffect(isPressed) { while (isPressed) { delay(stepDelay.coerceIn(1L, Long.MAX_VALUE)) pressedListener() } } IconButton( modifier = modifier, onClick = onClick, interactionSource = interactionSource ) { Icon( painter = if (isPressed) painterResource(id = selectedImage) else painterResource(id = unselectedImage), contentDescription = contentDescription, ) } }
Puntos clave sobre el código
MomentaryIconButtontoma ununselectedImage: Int, el ID de recurso de elemento de diseño para el ícono cuando no se presiona el botón, yselectedImage: Int, el ID de recurso de elemento de diseño para el ícono cuando se presiona el botón.- Usa un
interactionSourcepara hacer un seguimiento específico de las interacciones de "presión" del usuario. isPressedes verdadero cuando se presiona el botón de forma activa y falso en caso contrario. CuandoisPressedestrue, elLaunchedEffectingresa un bucle.- Dentro de este bucle, usa un
delay(constepDelay) para crear pausas entre las acciones de activación.coerceIngarantiza que la demora sea de al menos 1 ms para evitar bucles infinitos. - Se invoca
pressedListenerdespués de cada retraso dentro del bucle. Esto hace que la acción se repita.
- Dentro de este bucle, usa un
pressedListenerusarememberUpdatedStatepara garantizar que la lambdaonClick(la acción que se debe realizar) siempre sea la más actualizada de la composición más reciente.- El
Iconcambia la imagen que se muestra según si el botón está presionado o no.- Si
isPressedes verdadero, se muestraselectedImage. - De lo contrario, se muestra
unselectedImage.
- Si
Luego, usa este MomentaryIconButton en un ejemplo. En el siguiente fragmento, se muestran dos botones de ícono que controlan un contador:
@Preview() @Composable fun MomentaryIconButtonExample() { var pressedCount by remember { mutableIntStateOf(0) } Row( modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically ) { MomentaryIconButton( unselectedImage = R.drawable.fast_rewind, selectedImage = R.drawable.fast_rewind_filled, stepDelay = 100L, onClick = { pressedCount -= 1 }, contentDescription = "Decrease count button" ) Spacer(modifier = Modifier) Text("advanced by $pressedCount frames") Spacer(modifier = Modifier) MomentaryIconButton( unselectedImage = R.drawable.fast_forward, selectedImage = R.drawable.fast_forward_filled, contentDescription = "Increase count button", stepDelay = 100L, onClick = { pressedCount += 1 } ) } }
Puntos clave sobre el código
- El elemento
MomentaryIconButtonExampleque admite composición muestra unaRowque contiene dos instancias deMomentaryIconButtony un elementoTextque admite composición para compilar una IU que incremente y disminuya un contador. - Mantiene una variable de estado mutable
pressedCountconrememberymutableIntStateOf, inicializada en 0. Cuando cambiapressedCount, se vuelven a componer todos los elementos componibles que lo observan (como el elemento componibleText) para reflejar el valor nuevo. - El primer
MomentaryIconButtondisminuyepressedCountcuando se hace clic en él o se mantiene presionado. - El segundo
MomentaryIconButtonaumentapressedCountcuando se hace clic en él o se mantiene presionado. - Ambos botones usan un
stepDelayde 100 milisegundos, lo que significa que la acciónonClickse repite cada 100 ms mientras se mantiene presionado un botón.
Resultado
En el siguiente video, se muestra la IU con los botones de ícono y el contador:
Actualización de M3 Expressive
Con la actualización de M3 Expressive, los botones de ícono admiten opciones adicionales de tamaño, esquina y ancho, y pueden cambiar de forma cuando se presionan o seleccionan. Cuando se colocan en grupos de botones estándar, los botones de ícono también interactúan con los botones vecinos cuando se presionan.
Forma animada
Los botones de ícono pueden animar su forma cuando se presionan, y los botones de ícono de activación pueden animar su forma según su estado de marcado. Para habilitar la animación de formas, pasa IconButtonDefaults.shapes() o IconButtonDefaults.toggleableShapes() al parámetro shapes de IconButton o IconToggleButton.
Botones de ícono
En el siguiente fragmento, se muestra cómo implementar un botón de ícono que anima su forma cuando se presiona:
@Composable fun IconButtonWithAnimatedShapeSample() { IconButton( onClick = { /* doSomething() */ }, shapes = IconButtonDefaults.shapes(), ) { Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description") } }
Botones de activación con ícono
En el siguiente fragmento, se muestra cómo implementar un botón de activación con ícono que anima su forma según su estado de marcado:
@Composable fun IconToggleButtonWithAnimatedShapeSample() { var checked by remember { mutableStateOf(false) } IconToggleButton( checked = checked, onCheckedChange = { checked = it }, shapes = IconButtonDefaults.toggleableShapes(), ) { if (checked) { Icon(painter = rememberVectorPainter(AppIcons.LockFilled), contentDescription = "Localized description") } else { Icon(painter = rememberVectorPainter(AppIcons.Lock), contentDescription = "Localized description") } } }
Variantes de tamaño, ancho y forma
Los botones de ícono están disponibles en formas redondas y cuadradas, cinco tamaños y tres anchos.
Para obtener más información sobre las actualizaciones de M3 Expressive para los botones de ícono, consulta los lineamientos de los botones de ícono de Material Design 3.
Existen cinco variantes de tamaño de botones de ícono: extrapequeño, pequeño, mediano, grande y extragrande. Cada tamaño admite tres opciones de ancho: uniforme (predeterminado), estrecho y ancho.
Los botones de ícono están disponibles en variantes de esquinas redondeadas o cuadradas, y los botones de ícono de activación cambian de forma cuando se presionan o seleccionan.

Para obtener orientación sobre cómo elegir entre las variantes de esquinas, consulta los lineamientos de los botones de ícono de Material Design 3.