# Action Button

Action buttons allow users to perform an action. They are used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren’t meant to draw a lot of attention. Action buttons are the preferred buttons for taking actions on tables and plots that in some way alter tables, such as applying a filter.

## Example

```python
from deephaven import ui

btn = ui.action_button("Press me", on_press=lambda: print("Button clicked"))
```

## UI Recommendations

Recommendations for creating clear and effective action buttons:

1. Button text should be clear and concise. A maximum of 4 words or 20 characters is recommended.
2. Use verbs for button text to indicate the action that will be taken when the button is clicked. For example, “Save”, “Delete”, or “Add friend”, rather than “Ok” or “Cancel”. Nouns or adjectives tend to be less clear.
3. Use sentence case for button text with more than one word. For example, “Add friend” instead of “Add Friend” or “ADD FRIEND”.
4. No punctuation is needed at the end of the button text.
5. For icon-only buttons, include a tooltip

Consider using [`button`](button.md) to draw attention to important actions users need to perform or for navigating to a different page. To represent a binary choice, use a [`toggle_button`](toggle_button.md) instead. If you have a collection of related buttons, you can group them using an [`action_group`](action_group.md).

## Events

`action_button` accepts a value to display and can trigger actions based on events such as setting state when pressed. See the [API Reference]() for a full list of available events.

```python
from deephaven import ui


@ui.component
def counter():
    count, set_count = use_state(0)
    return ui.action_button(
        f"Pressed {count} times",
        on_press=lambda: set_count(count + 1),
    )


counter_example = counter()
```

## Icon Buttons

Action buttons can have icons when necessary to provide additional context. If no visible label is provided (e.g., an icon-only button), an alternative text label must be provided to identify the control for accessibility using the `aria-label` prop. See [icon](icon.md) for a list of available icons.

```python
from deephaven import ui


@ui.component
def ui_button_group():
    iconAndLabel = ui.button_group(
        ui.action_button("Restart", ui.icon("vsDebugRestart")),
        ui.action_button("Record", ui.icon("vsRecord")),
        ui.action_button("Play", ui.icon("vsDebugPause")),
        ui.action_button("Pause", ui.icon("vsDebugStart")),
        ui.action_button("Edit", ui.icon("vsEdit")),
        ui.action_button("Configure", ui.icon("vsGear")),
    )
    iconOnly = ui.button_group(
        ui.action_button(ui.icon("vsDebugRestart"), aria_label="Restart"),
        ui.action_button(ui.icon("vsRecord"), aria_label="Record"),
        ui.action_button(ui.icon("vsDebugPause"), aria_label="Play"),
        ui.action_button(ui.icon("vsDebugStart"), aria_label="Pause"),
        ui.action_button(ui.icon("vsEdit"), aria_label="Edit"),
        ui.action_button(ui.icon("vsGear"), aria_label="Configure"),
    )
    return [iconAndLabel, iconOnly]


my_action_buttons = ui_button_group()
```

## Quiet State

Action buttons can have no visible background until they’re interacted with. This style works best when a clear layout (vertical stack, table, grid) makes it easy to parse the buttons. Too many quiet components in a small space can be hard to read.

```python
from deephaven import ui

btn = ui.action_button("Quiet button", is_quiet=True)
```

## Disabled State

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

```python
from deephaven import ui

btn = ui.action_button("Disabled button", is_disabled=True)
```

## Static Colors

Static-color buttons are available in white and black. They don’t dynamically change in response to the user’s theme. They should only be used over fixed-color backgrounds, not over theme colors that may change.

```python
from deephaven import ui


@ui.component
def static_buttons():
    return [
        ui.view(
            ui.action_button(
                "White outline",
                static_color="white",
            ),
            background_color="#000066",
            padding="size-300",
        ),
        ui.view(
            ui.action_button(
                "Black outline",
                static_color="black",
            ),
            background_color="#FFFF00",
            padding="size-300",
        ),
    ]


static_buttons_example = static_buttons()
```

## API Reference

ActionButtons allow users to perform an action. They're used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren't meant to draw a lot of attention.
Python implementation for the Adobe React Spectrum ActionButton component: https://react-spectrum.adobe.com/react-spectrum/ActionButton.html

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

<ParamTable param={{"module_name": "deephaven.ui.", "name": "action_button", "parameters": [{"name": "*children", "type": "Any", "description": "The content to display inside the button."}, {"name": "type", "type": "Literal['button', 'submit', 'reset']", "description": "The type of button to render. (default: \"button\")", "default": "'button'"}, {"name": "on_press", "type": "Callable[[PressEvent], None] | None", "description": "Function called when the button is pressed.", "default": "None"}, {"name": "on_press_start", "type": "Callable[[PressEvent], None] | None", "description": "Function called when the button is pressed.", "default": "None"}, {"name": "on_press_end", "type": "Callable[[PressEvent], None] | None", "description": "Function called when a press interaction ends, either over the target or when the pointer leaves the target.", "default": "None"}, {"name": "on_press_up", "type": "Callable[[PressEvent], None] | None", "description": "Function called when the button is released.", "default": "None"}, {"name": "on_press_change", "type": "Callable[[bool], None] | None", "description": "Function called when the press state changes.", "default": "None"}, {"name": "on_focus", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the button receives focus.", "default": "None"}, {"name": "on_blur", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the button loses focus.", "default": "None"}, {"name": "on_focus_change", "type": "Callable[[bool], None] | None", "description": "Function called when the focus state changes.", "default": "None"}, {"name": "on_key_down", "type": "Callable[[KeyboardEvent], None] | None", "description": "Function called when a key is pressed.", "default": "None"}, {"name": "on_key_up", "type": "Callable[[KeyboardEvent], None] | None", "description": "Function called when a key is released.", "default": "None"}, {"name": "auto_focus", "type": "bool | None", "description": "Whether the button should automatically get focus when the page loads.", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the button is disabled.", "default": "None"}, {"name": "is_quiet", "type": "bool | None", "description": "Whether the button should be quiet.", "default": "None"}, {"name": "static_color", "type": "Literal['white', 'black'] | None", "description": "The static color style to apply. Useful when the button appears over a color background.", "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 much 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 much 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 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 align_items 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": "Specifies 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": "The name of the grid area to place the element in.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "The name of the grid row to place the element in.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "The name of the grid row to start the element in.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "The name of the grid row to end the element in.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "The name of the grid column to place the element in.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "The name of the grid column to start the element in.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "The name of the grid column to end the element in.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin to apply around the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin to apply above the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin to apply below the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin to apply before the element.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin to apply after the element.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin to apply to the left and right of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin to apply to the top and bottom 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 positioned.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "A unique identifier for the element.", "default": "None"}, {"name": "exclude_from_tab_order", "type": "bool | None", "description": "Whether the element should be excluded from the tab order.", "default": "None"}, {"name": "aria_expanded", "type": "Literal['true', 'false'] | bool | None", "description": "Whether the element is expanded.", "default": "None"}, {"name": "aria_haspopup", "type": "Literal['true', 'false'] | bool | Literal['menu', 'listbox', 'tree', 'grid', 'dialog'] | None", "description": "Whether the element has a popup.", "default": "None"}, {"name": "aria_controls", "type": "str | None", "description": "The id of the element that the element controls.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "The label for the element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "The id of the element that labels the element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "The id of the element that describes the element.", "default": "None"}, {"name": "aria_pressed", "type": "Literal['true', 'false'] | bool | Literal['mixed'] | None", "description": "Whether the element is pressed.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "The details for the element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />