# ButtonGroupScope

Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/ButtonGroup.kt+class:androidx.compose.material3.ButtonGroupScope) Common/AllAndroid/JVM
- Cmn

  ```
  sealed interface ButtonGroupScope
  ```

*** ** * ** ***

Button group scope used to indicate a `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).weight(kotlin.Float)` and `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).animateWidth(androidx.compose.foundation.interaction.InteractionSource)` of a child element. Also defines the DSL to build the content of a `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`

## Summary

| ### Public functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).align(androidx.compose.ui.Alignment.Vertical)(alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment.Vertical)` Align the element vertically within the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).animateWidth(androidx.compose.foundation.interaction.InteractionSource)(interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource)` Specifies the interaction source to use with this item. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).animateWidth(androidx.compose.foundation.interaction.InteractionSource,androidx.compose.ui.unit.Dp)( interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource, compressionLimit: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp )` Specifies the interaction source to use with this item. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#clickableItem(kotlin.Function0,kotlin.String,kotlin.Function0,kotlin.Float,kotlin.Boolean)( onClick: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, icon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, weight: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Adds a clickable item to the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#customItem(kotlin.Function0,kotlin.Function1)( buttonGroupContent: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, menuContent: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupMenuState) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html )` Adds a custom item to the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#toggleableItem(kotlin.Boolean,kotlin.String,kotlin.Function1,kotlin.Function0,kotlin.Float,kotlin.Boolean)( checked: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, onCheckedChange: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html, icon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)?, weight: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Adds a toggleable item to the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier` | `https://developer.android.com/reference/kotlin/androidx/compose/ui/Modifier.https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).weight(kotlin.Float)( weight: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0, fromInclusive = false) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html )` Size the element's width proportional to its `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).weight(kotlin.Float)` relative to other weighted sibling elements in the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`. | Cmn |

## Public functions

### Modifier.align

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/ButtonGroup.kt+function:align)

```
fun Modifier.align(alignment: Alignment.Vertical): Modifier
```

Align the element vertically within the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`. This alignment will have priority over the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`'s `verticalAlignment` parameter.

| Parameters |
|---|---|
| `alignment: https://developer.android.com/reference/kotlin/androidx/compose/ui/Alignment.Vertical` | the vertical alignment of the element |

### Modifier.animateWidth

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/ButtonGroup.kt+function:animateWidth)

```
fun Modifier.animateWidth(interactionSource: InteractionSource): Modifier
```

Specifies the interaction source to use with this item. This is used to listen to events and animate growing the pressed button and shrink the neighbor(s).

```kotlin
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.calculateEndPadding
import androidx.compose.foundation.layout.size
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Restaurant
import androidx.compose.material.icons.filled.Work
import androidx.compose.material.icons.outlined.Home
import androidx.compose.material.icons.outlined.Restaurant
import androidx.compose.material.icons.outlined.Work
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.ButtonGroup
import androidx.compose.material3.ButtonGroupDefaults
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.material3.ToggleButton
import androidx.compose.material3.ToggleButtonDefaults
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalLayoutDirection
import androidx.compose.ui.text.style.TextOverflow

val options = listOf("Work", "Restaurant", "Home")
val unCheckedIcons = listOf(Icons.Outlined.Work, Icons.Outlined.Restaurant, Icons.Outlined.Home)
val checkedIcons = listOf(Icons.Filled.Work, Icons.Filled.Restaurant, Icons.Filled.Home)
val checked = rememberSaveable { mutableStateListOf(false, false, false) }
val interactionSources = remember { List(options.size) { MutableInteractionSource() } }
ButtonGroup(
    overflowIndicator = { menuState ->
        ButtonGroupDefaults.OverflowIndicator(menuState = menuState)
    },
    expandedRatio = 1f,
) {
    options.forEachIndexed { index, label ->
        customItem(
            buttonGroupContent = {
                val contentPadding = ButtonDefaults.ButtonWithIconContentPadding
                val layoutDirection = LocalLayoutDirection.current
                ToggleButton(
                    checked = checked[index],
                    onCheckedChange = { checked[index] = it },
                    shapes =
                        when (index) {
                            0 -> ButtonGroupDefaults.connectedLeadingButtonShapes()
                            options.lastIndex ->
                                ButtonGroupDefaults.connectedTrailingButtonShapes()
                            else -> ButtonGroupDefaults.connectedMiddleButtonShapes()
                        },
                    contentPadding = contentPadding,
                    interactionSource = interactionSources[index],
                    modifier =
                        Modifier.animateWidth(
                            interactionSource = interactionSources[index],
                            compressionLimit =
                                contentPadding.calculateEndPadding(layoutDirection),
                        ),
                ) {
                    Icon(
                        if (checked[index]) checkedIcons[index] else unCheckedIcons[index],
                        contentDescription = "Localized description",
                    )
                    Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing))
                    Text(
                        text = label,
                        softWrap = false,
                        maxLines = 1,
                        overflow = TextOverflow.Visible,
                    )
                }
            },
            menuContent = {
                DropdownMenuItem(
                    leadingIcon = { checkedIcons[index] },
                    text = { Text(label) },
                    onClick = {},
                    interactionSource = interactionSources[index],
                )
            },
        )
    }
}
```

| Parameters |
|---|---|
| `interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource` | the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource` that button group will observe. |

### Modifier.animateWidth

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/ButtonGroup.kt+function:animateWidth)

```
fun Modifier.animateWidth(
    interactionSource: InteractionSource,
    compressionLimit: Dp
): Modifier
```

Specifies the interaction source to use with this item. This is used to listen to events and animate growing the pressed button and shrink the neighbor(s).

```kotlin
import androidx.compose.foundation.interaction.MutableInteractionSource
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.calculateEndPadding
import androidx.compose.foundation.layout.size
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Restaurant
import androidx.compose.material.icons.filled.Work
import androidx.compose.material.icons.outlined.Home
import androidx.compose.material.icons.outlined.Restaurant
import androidx.compose.material.icons.outlined.Work
import androidx.compose.material3.ButtonDefaults
import androidx.compose.material3.ButtonGroup
import androidx.compose.material3.ButtonGroupDefaults
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.Icon
import androidx.compose.material3.Text
import androidx.compose.material3.ToggleButton
import androidx.compose.material3.ToggleButtonDefaults
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.saveable.rememberSaveable
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalLayoutDirection
import androidx.compose.ui.text.style.TextOverflow

val options = listOf("Work", "Restaurant", "Home")
val unCheckedIcons = listOf(Icons.Outlined.Work, Icons.Outlined.Restaurant, Icons.Outlined.Home)
val checkedIcons = listOf(Icons.Filled.Work, Icons.Filled.Restaurant, Icons.Filled.Home)
val checked = rememberSaveable { mutableStateListOf(false, false, false) }
val interactionSources = remember { List(options.size) { MutableInteractionSource() } }
ButtonGroup(
    overflowIndicator = { menuState ->
        ButtonGroupDefaults.OverflowIndicator(menuState = menuState)
    },
    expandedRatio = 1f,
) {
    options.forEachIndexed { index, label ->
        customItem(
            buttonGroupContent = {
                val contentPadding = ButtonDefaults.ButtonWithIconContentPadding
                val layoutDirection = LocalLayoutDirection.current
                ToggleButton(
                    checked = checked[index],
                    onCheckedChange = { checked[index] = it },
                    shapes =
                        when (index) {
                            0 -> ButtonGroupDefaults.connectedLeadingButtonShapes()
                            options.lastIndex ->
                                ButtonGroupDefaults.connectedTrailingButtonShapes()
                            else -> ButtonGroupDefaults.connectedMiddleButtonShapes()
                        },
                    contentPadding = contentPadding,
                    interactionSource = interactionSources[index],
                    modifier =
                        Modifier.animateWidth(
                            interactionSource = interactionSources[index],
                            compressionLimit =
                                contentPadding.calculateEndPadding(layoutDirection),
                        ),
                ) {
                    Icon(
                        if (checked[index]) checkedIcons[index] else unCheckedIcons[index],
                        contentDescription = "Localized description",
                    )
                    Spacer(Modifier.size(ToggleButtonDefaults.IconSpacing))
                    Text(
                        text = label,
                        softWrap = false,
                        maxLines = 1,
                        overflow = TextOverflow.Visible,
                    )
                }
            },
            menuContent = {
                DropdownMenuItem(
                    leadingIcon = { checkedIcons[index] },
                    text = { Text(label) },
                    onClick = {},
                    interactionSource = interactionSources[index],
                )
            },
        )
    }
}
```

| Parameters |
|---|---|
| `interactionSource: https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource` | the `https://developer.android.com/reference/kotlin/androidx/compose/foundation/interaction/InteractionSource` that button group will observe. |
| `compressionLimit: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp` | the `https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Dp` used to determine the maximum compression that this item will be able to squish by. |

### clickableItem

Cmn

```
fun clickableItem(
    onClick: () -> Unit,
    label: String,
    icon: (@Composable () -> Unit)? = null,
    weight: Float = Float.NaN,
    enabled: Boolean = true
): Unit
```

Adds a clickable item to the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`.

| Parameters |
|---|---|
| `onClick: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The action to perform when the item is clicked. |
| `label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The text label for the item. |
| `icon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | An optional composable representing the item's icon. |
| `weight: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = Float.NaN` | the weight to be applied to this item, please see `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).weight(kotlin.Float)` |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Whether the item is enabled. |

### customItem

Cmn

```
fun customItem(
    buttonGroupContent: @Composable () -> Unit,
    menuContent: @Composable (ButtonGroupMenuState) -> Unit
): Unit
```

Adds a custom item to the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`.

| Parameters |
|---|---|
| `buttonGroupContent: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The composable to display in the app bar. |
| `menuContent: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable (https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupMenuState) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The composable to display in the overflow menu. It receives an `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupMenuState` instance. |

### toggleableItem

Cmn

```
fun toggleableItem(
    checked: Boolean,
    label: String,
    onCheckedChange: (Boolean) -> Unit,
    icon: (@Composable () -> Unit)? = null,
    weight: Float = Float.NaN,
    enabled: Boolean = true
): Unit
```

Adds a toggleable item to the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`.

| Parameters |
|---|---|
| `checked: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | Whether the item is currently checked. |
| `label: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The text label for the item. |
| `onCheckedChange: (https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | The action to perform when the item's checked state changes. |
| `icon: (@https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)? = null` | An optional composable representing the item's icon. |
| `weight: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html = Float.NaN` | the weight to be applied to this item, please see `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).weight(kotlin.Float)` |
| `enabled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | Whether the item is enabled. |

### Modifier.weight

Cmn Artifact: [androidx.compose.material3:material3](https://developer.android.com/jetpack/androidx/releases/compose-material3) [View Source](https://cs.android.com/search?q=file:androidx/compose/material3/ButtonGroup.kt+function:weight)

```
fun Modifier.weight(
    weight: @FloatRange(from = 0.0, fromInclusive = false) Float
): Modifier
```

Size the element's width proportional to its `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroupScope#(androidx.compose.ui.Modifier).weight(kotlin.Float)` relative to other weighted sibling elements in the `https://developer.android.com/reference/kotlin/androidx/compose/material3/ButtonGroup.composable#ButtonGroup(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Float,androidx.compose.foundation.layout.Arrangement.Horizontal,androidx.compose.ui.Alignment.Vertical,kotlin.Function1)`. The parent will divide the horizontal space remaining after measuring unweighted child elements and distribute it according to this weight.

| Parameters |
|---|---|
| `weight: @https://developer.android.com/reference/kotlin/androidx/annotation/FloatRange(from = 0.0, fromInclusive = false) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | The proportional width to give to this element, as related to the total of all weighted siblings. Must be positive. |