# Action Group

An action group is a UI component that groups multiple actions together.

## Example

```python
from deephaven import ui


my_action_group_basic = ui.action_group(
    ui.item("Add"),
    ui.item("Edit"),
    ui.item("Delete"),
)
```

![Action Group Basic Example](../_assets/action_group_basic.png)

## UI recommendations

Consider using a [`button_group`](./button_group.md) to align multiple buttons that do not necessarily correspond to an action.

## Icons

Icons can be added to action group items by wrapping the label in a `ui.text` element and adding a `ui.icon` as a sibling component.

```python
from deephaven import ui


my_action_group_icon_example = ui.action_group(
    ui.item(ui.icon("edit"), ui.text("Edit")),
    ui.item(ui.icon("copy"), ui.text("Copy")),
    ui.item(ui.icon("trash"), ui.text("Delete")),
)
```

The `button_label_behavior` prop can be set to “hide” label text within buttons and show it in a tooltip on hover.

```python
from deephaven import ui


my_action_group_button_label_behavior_example = ui.action_group(
    ui.item(ui.icon("edit"), ui.text("Edit")),
    ui.item(ui.icon("copy"), ui.text("Copy")),
    ui.item(ui.icon("trash"), ui.text("Delete")),
    button_label_behavior="hide",
)
```

## Selection

Action groups support multiple selection modes, which are configurable via the `selection_mode` prop.

The `default_selected_keys` can be used for uncontrolled default selections.

```python
from deephaven import ui


my_action_group_default_selected_keys_example = ui.action_group(
    ui.item("Grid view", key="grid"),
    ui.item("List view", key="list"),
    ui.item("Gallery view", key="gallery"),
    selection_mode="single",
    default_selected_keys=["list"],
)
```

The `selected_keys` prop can be used for controlled selections.

```python
from deephaven import ui


@ui.component
def ui_action_group_selected_keys_example():
    selected, set_selected = ui.use_state([])
    return [
        ui.action_group(
            ui.item("Grid view", key="grid"),
            ui.item("List view", key="list"),
            ui.item("Gallery view", key="gallery"),
            selection_mode="multiple",
            selected_keys=selected,
            on_change=set_selected,
        ),
        ui.text(f"Current selection (controlled): {selected}"),
    ]


my_action_group_selected_keys_example = ui_action_group_selected_keys_example()
```

## Events

The `on_selection_change` property is triggered whenever the value in the action group selection changes.

```python
from deephaven import ui


@ui.component
def ui_action_group_on_change_example():
    selected_option, set_selected_option = ui.use_state("")
    return [
        ui.action_group(
            ui.item("Grid view", key="grid"),
            ui.item("List view", key="list"),
            ui.item("Gallery view", key="gallery"),
            selection_mode="single",
            on_selection_change=set_selected_option,
        ),
        ui.text(f"You have selected: {selected_option}"),
    ]


my_action_group_on_change_example = ui_action_group_on_change_example()
```

## Collapsing Behavior

By default, the items of an action group wrap to a new line when space is limited. To keep them in a single line, set the `overflow_mode` prop to “collapse”, which collapses the items into a menu.

```python
from deephaven import ui


my_action_group_overflow_example = ui.action_group(
    ui.item(ui.icon("edit"), ui.text("Edit")),
    ui.item(ui.icon("copy"), ui.text("Copy")),
    ui.item(ui.icon("trash"), ui.text("Delete")),
    ui.item(ui.icon("move"), ui.text("Move")),
    ui.item(ui.icon("diff_multiple"), ui.text("Duplicate")),
    overflow_mode="collapse",
    max_width=250,
)
```

When selection is enabled, the action group collapses all items into a menu when space is limited, with a highlighted menu button indicating a selection.

```python
from deephaven import ui

my_action_group_selection_collapsing_example = ui.action_group(
    ui.item(ui.icon("edit"), ui.text("Edit")),
    ui.item(ui.icon("copy"), ui.text("Copy")),
    ui.item(ui.icon("trash"), ui.text("Delete")),
    static_color="white",
    summary_icon=ui.icon("vsSearch"),
    overflow_mode="collapse",
    selection_mode="multiple",
    is_emphasized=True,
    max_width=10,
)
```

## Quiet State

The `is_quiet` prop makes action groups “quiet”. This can be useful when the action group and its corresponding styling should not distract users from surrounding content.

```python
from deephaven import ui


my_action_group_is_quiet_example = ui.action_group(
    ui.item("Add"),
    ui.item("Edit"),
    ui.item("Delete"),
    is_quiet=True,
)
```

## Emphasized

The `is_emphasized` prop makes the selected action item the user’s accent color, adding a visual prominence to the selection.

```python
from deephaven import ui


my_action_group_is_emphasized_example = ui.action_group(
    ui.item("Dogs"),
    ui.item("Cats"),
    ui.item("Fish"),
    selected_keys=["Dogs"],
    selection_mode="single",
    is_emphasized=True,
)
```

## Static Color

The `static_color` prop can be used when the action group is placed over a color background.

```python
from deephaven import ui


my_action_group_static_color_example = ui.view(
    ui.action_group(
        ui.item(ui.icon("edit"), ui.text("Edit")),
        ui.item(ui.icon("copy"), ui.text("Copy")),
        ui.item(ui.icon("trash"), ui.text("Delete")),
        static_color="white",
    ),
    background_color="blue-700",
    padding="size-500",
)
```

## Disabled State

Action groups can be disabled to prevent user interaction. This is useful when the group is not currently available, but the button should still be visible.

```python
from deephaven import ui


my_action_group_is_disabled_example = ui.action_group(
    ui.item("Add"),
    ui.item("Edit"),
    ui.item("Delete"),
    is_disabled=True,
)
```

## Orientation

While aligned horizontally by default, the axis with which the action items align can be changed via the `orientation` prop.

```python
from deephaven import ui


my_action_group_orientation_example = ui.action_group(
    ui.item("Add"),
    ui.item("Edit"),
    ui.item("Delete"),
    orientation="vertical",
)
```

## Density

The `density` prop can increase or reduce margins between action buttons. When the `is_quiet` prop is set to true, margin size is reduced.

```python
from deephaven import ui


@ui.component
def ui_action_group_density_examples():
    return [
        ui.action_group(
            ui.item(ui.icon("edit")),
            ui.item(ui.icon("copy")),
            ui.item(ui.icon("trash")),
            density="compact",
        ),
        ui.action_group(
            ui.item(ui.icon("edit")),
            ui.item(ui.icon("copy")),
            ui.item(ui.icon("trash")),
            is_quiet=True,
            density="compact",
        ),
        ui.action_group(
            ui.item(ui.icon("edit")),
            ui.item(ui.icon("copy")),
            ui.item(ui.icon("trash")),
            density="spacious",
        ),
    ]


my_action_group_density_examples = ui_action_group_density_examples()
```

## Justified

The `is_justified` prop evenly divides all available horizontal space among the action items.

```python
from deephaven import ui


my_action_group_is_justified_example = ui.flex(
    ui.action_group(
        ui.item(ui.icon("edit")),
        ui.item(ui.icon("copy")),
        ui.item(ui.icon("trash")),
        is_justified=True,
        density="compact",
    ),
    width="size-3000",
    direction="column",
)
```

## API Reference

An action grouping of action items that are related to each other.

**Returns:** `Element` The rendered action_group element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "action_group", "parameters": [{"name": "*children", "type": "Any", "description": "The children of the action group."}, {"name": "is_emphasized", "type": "bool | None", "description": "Whether the action buttons should be displayed with emphasized style.", "default": "None"}, {"name": "density", "type": "Literal['compact', 'regular'] | None", "description": "Sets the amount of space between buttons.", "default": "'regular'"}, {"name": "is_justified", "type": "bool | None", "description": "Whether the ActionButtons should be justified in their container.", "default": "None"}, {"name": "is_quiet", "type": "bool | None", "description": "Whether ActionButtons should use the quiet style.", "default": "None"}, {"name": "static_color", "type": "Literal['white', 'black'] | None", "description": "The static color style to apply. Useful when the ActionGroup appears over a color background.", "default": "None"}, {"name": "overflow_mode", "type": "Literal['wrap', 'collapse'] | None", "description": "The behavior of the ActionGroup when the buttons do not fit in the available space.", "default": "'wrap'"}, {"name": "button_label_behavior", "type": "Literal['show', 'collapse', 'hide'] | None", "description": "Defines when the text within the buttons should be hidden and only the icon should be shown.", "default": "'show'"}, {"name": "summary_icon", "type": "Element | None", "description": "The icon displayed in the dropdown menu button when a selectable ActionGroup is collapsed.", "default": "None"}, {"name": "orientation", "type": "Literal['horizontal', 'vertical'] | None", "description": "The axis the ActionGroup should align with.", "default": "'horizontal'"}, {"name": "disabled_keys", "type": "Iterable[str] | None", "description": "A list of keys to disable.", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the ActionGroup is disabled. Shows that a selection exists, but is not available in that circumstance.", "default": "None"}, {"name": "selection_mode", "type": "Literal['SINGLE', 'MULTIPLE'] | None", "description": "The type of selection that is allowed in the collection.", "default": "None"}, {"name": "disallow_empty_selection", "type": "bool | None", "description": "Whether the collection allows empty selection.", "default": "None"}, {"name": "selected_keys", "type": "Literal['all'] | Iterable[str] | None", "description": "The currently selected keys in the collection (controlled).", "default": "None"}, {"name": "default_selected_keys", "type": "Literal['all'] | Iterable[str] | None", "description": "The initial selected keys in the collection (uncontrolled).", "default": "None"}, {"name": "on_action", "type": "Callable[[str], None] | None", "description": "Invoked when an action is taken on a child. Especially useful when selectionMode is none. The sole argument key is the key for the item.", "default": "None"}, {"name": "on_change", "type": "Callable[[str | int | float | bool], None] | None", "description": "Alias of on_selection_change. Handler that is called when the selection changes. The first argument is the selection, the second argument is the key of the list_view item.", "default": "None"}, {"name": "on_selection_change", "type": "Callable[[Sequence[str | int | float | bool]], None] | None", "description": "Handler that is called when the selection changes.", "default": "None"}, {"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": "aria_label", "type": "str | None", "description": "Defines a string value that labels the current element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "Identifies the element (or elements) that labels the current element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "Identifies the element (or elements) that describes the object.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "Identifies the element (or elements) that provide a detailed, extended description for the object.", "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"}]}} />