# Button Group

A button group is a UI component that groups buttons with related actions together and will automatically handle layout overflow nicely. Only buttons can be used within button groups.

## Example

```python
from deephaven import ui


my_button_group_basic = ui.button_group(
    ui.button("Rate Now", variant="accent"),
    ui.button("No, thanks", variant="primary", style="outline"),
    ui.button("Remind me later", variant="primary", style="outline"),
)
```

## UI Recommendations

Recommendations for creating button groups:

1. The most critical action in a button group should use an accent, or negative button style, while other actions should be primary outline buttons.
2. Button groups should be left-aligned to follow content such as blocks of text, center-aligned in empty states, and right-aligned in container components like dialogs, popovers, or cards.
3. Button priority should match text alignment: for left-aligned text, the most critical button is on the left; for right- or center-aligned text, the most critical button is on the right.
4. Icons should be used for higher-priority actions if used in the button group. If the most critical action does not have an icon, avoid using icons for the other lower-priority actions.

Consider using an [`action_group`](action_group.md) to allow the user to select from a list of actions.

## Content

A button group is used to handle button overflow and, thus, expects buttons as children. It switches to a vertical layout when horizontal space is limited.

```python
from deephaven import ui


my_button_group_content_space_example = ui.view(
    ui.button_group(
        ui.button("Rate Now", variant="accent", style="outline"),
        ui.button("Remind me later", variant="primary", style="outline"),
        ui.button("No, thanks", variant="primary", style="outline"),
    ),
    width=200,
    border_width="thin",
    padding="size-100",
)
```

## Orientation

Setting the `orientation` prop to “vertical” will prevent any spacing-related dynamic orientation changes.

The button group will remain in the orientation regardless of the width.

```python
from deephaven import ui


my_button_group_orientation_example = ui.button_group(
    ui.button("No, thanks", variant="primary", style="outline"),
    ui.button("Remind me later", variant="primary", style="outline"),
    ui.button("Rate Now", variant="accent"),
    orientation="vertical",
)
```

## Alignment

By default, button groups are start-aligned to accord with content, but they can be set to have a different alignment using the `alignment` prop.

```python
from deephaven import ui


@ui.component
def ui_button_group_alignment_examples():
    return [
        ui.button_group(
            ui.button("No, thanks", variant="primary", style="outline"),
            ui.button("Remind me later", variant="primary", style="outline"),
            ui.button("Rate Now", variant="accent"),
            align="center",
        ),
        ui.button_group(
            ui.button("No, thanks", variant="primary", style="outline"),
            ui.button("Remind me later", variant="primary", style="outline"),
            ui.button("Rate Now", variant="accent"),
            align="end",
        ),
    ]


my_button_group_alignment_examples = ui_button_group_alignment_examples()
```

## Disabled state

The `is_disabled` prop disables the button group to prevent user interaction. This is useful when the button group should be visible but not available for selection.

```python
from deephaven import ui


my_button_group_is_disabled_example = ui.button_group(
    ui.button("No, thanks", variant="primary", style="outline"),
    ui.button("Remind me later", variant="primary", style="outline"),
    ui.button("Rate Now", variant="accent"),
    is_disabled=True,
)
```

## API Reference

A button group is a grouping of button whose actions are related to each other.

**Returns:** `Element` The rendered button group element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "button_group", "parameters": [{"name": "*children", "type": "Any", "description": "The children of the button group."}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the button group is disabled.", "default": "None"}, {"name": "orientation", "type": "Literal['horizontal', 'vertical']", "description": "The axis the ButtonGroup should align with. Setting this to 'vertical' will prevent any switching behaviours between 'vertical' and horizontal'.", "default": "'horizontal'"}, {"name": "align", "type": "Literal['start', 'center', 'end']", "description": "The alignment of the buttons within the ButtonGroup.", "default": "'start'"}, {"name": "flex", "type": "str | float | bool | None", "description": "When used in a flex layout, specifies how the element will grow or shrink to fit the space available.", "default": "None"}, {"name": "flex_grow", "type": "float | None", "description": "When used in a flex layout, specifies how the element will grow to fit the space available.", "default": "None"}, {"name": "flex_shrink", "type": "float | None", "description": "When used in a flex layout, specifies how the element will shrink to fit the space available.", "default": "None"}, {"name": "flex_basis", "type": "str | float | None", "description": "When used in a flex layout, specifies the initial main size of the element.", "default": "None"}, {"name": "align_self", "type": "Literal['auto', 'normal', 'start', 'end', 'center', 'flex-start', 'flex-end', 'self-start', 'self-end', 'stretch'] | None", "description": "Overrides the alignItems property of a flex or grid container.", "default": "None"}, {"name": "justify_self", "type": "Literal['auto', 'normal', 'start', 'end', 'flex-start', 'flex-end', 'self-start', 'self-end', 'center', 'left', 'right', 'stretch'] | None", "description": "Species how the element is justified inside a flex or grid container.", "default": "None"}, {"name": "order", "type": "int | None", "description": "The layout order for the element within a flex or grid container.", "default": "None"}, {"name": "grid_area", "type": "str | None", "description": "When used in a grid layout specifies, specifies the named grid area that the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "When used in a grid layout, specifies the row the element should be placed in within the grid.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "When used in a grid layout, specifies the column the element should be placed in within the grid.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting row to span within the grid.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending row to span within the grid.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "When used in a grid layout, specifies the starting column to span within the grid.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "When used in a grid layout, specifies the ending column to span within the grid.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin for all four sides of the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin for the top side of the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin for the bottom side of the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin for the logical start side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin for the logical end side of the element, depending on layout direction.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin for the left and right sides of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin for the top and bottom sides of the element.", "default": "None"}, {"name": "width", "type": "str | float | None", "description": "The width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "max_height", "type": "str | float | None", "description": "The maximum height of the element.", "default": "None"}, {"name": "position", "type": "Literal['static', 'relative', 'absolute', 'fixed', 'sticky'] | None", "description": "Specifies how the element is position.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The top position of the element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The bottom position of the element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The left position of the element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The right position of the element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The logical start position of the element, depending on layout direction.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The logical end position of the element, depending on layout direction.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stacking order for the element", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Hides the element.", "default": "None"}, {"name": "id", "type": "str | None", "description": "The unique identifier of the element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "Set the CSS className for the element. Only use as a last resort. Use style props instead.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "Set the inline style for the element. Only use as a last resort. Use style props instead.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />