# Button element

Allows users a direct path to performing basic actions. A click sends your app a `block_actions` payload; a button with a `url` also opens the link.

| | |
|---|---|
| **Type** | `button` |
| **Available in** | Messages, Modals, Home tab |
| **Works in blocks** | [Section block](https://workstation.repzo.com/docs/developers/block-kit/blocks/section-block), [Actions block](https://workstation.repzo.com/docs/developers/block-kit/blocks/actions-block), [Card block](https://workstation.repzo.com/docs/developers/block-kit/blocks/card-block), [Data table block](https://workstation.repzo.com/docs/developers/block-kit/blocks/data-table-block) |

## Usage

Use a button as a section block's `accessory`, in an actions block's `elements`, in a card block's `actions` (up to 3 buttons) or in a data table's `action_cell` cells.

When someone clicks it, Repzo POSTs a signed `block_actions` payload to every subscription of your app that lists the `block_actions` event. `actions[0]` describes the click:

```json
{
  "type": "button",
  "action_id": "approve_quote",
  "block_id": "quote_q1042",
  "text": { "type": "plain_text", "text": "Approve" },
  "style": "primary",
  "value": "Q-1042",
  "action_ts": "1793786400.000000"
}
```

The payload around it carries `user`, `container` (`type: "message"` with `message_ts`, `channel_id`, `is_ephemeral` and `thread_ts` for replies; `type: "view"` with `view_id` in modals and the Home tab), `channel` and `message` (messages only), `view` (views only), `state.values` with the current value of every other control, a `response_url` for messages, and a `trigger_id` you can use within 60 seconds to open a modal.

A button with a `url` opens the link — Repzo pages open inside the app, other links in a new tab — **and** still sends `block_actions`, as on Slack. With `confirm`, the dialog appears first and nothing happens if the reader cancels. In a card or data table, the action's `block_id` is the card's or the table's.

## Fields

| Field | Type | Description | Required? |
|---|---|---|---|
| `type` | String | The type of element. In this case `type` is always `button`. | Required |
| `text` | [Text object](https://workstation.repzo.com/docs/developers/block-kit/objects/text-object) | A text object that defines the button's text. Can only be of `type: plain_text`. `text` may truncate with ~30 characters. Maximum length for the `text` in this field is 75 characters. | Required |
| `action_id` | String | An identifier for the action triggered when the button is clicked. You can use this when you receive an interaction payload to identify the source of the action. Should be unique among all other `action_id`s in the containing block. Maximum length is 255 characters. If you leave it out, Repzo generates one. | Optional |
| `url` | String | A URL to load in the reader's browser when the button is clicked. Only `http` and `https` links are opened. Maximum length is 3000 characters. You still receive the `block_actions` payload. | Optional |
| `value` | String | The value to send along with the interaction payload. Maximum length is 2000 characters. | Optional |
| `style` | String | Decorates buttons with alternative visual color schemes. Use this option with restraint. `primary` gives buttons a green look, ideal for affirmation or confirmation actions, and should only be used for one button within a set. `danger` gives buttons a red look and should be used when the action is destructive. Use `danger` even more sparingly than `primary`. If you don't include this field, the default button style will be used. | Optional |
| `confirm` | [Confirmation dialog object](https://workstation.repzo.com/docs/developers/block-kit/objects/confirmation-dialog-object) | A confirm object that defines an optional confirmation dialog that appears after the button is clicked. If the reader cancels, nothing is sent to your app. | Optional |
| `accessibility_label` | String | A label for longer descriptive text about the button. This label will be read out by screen readers _instead of_ the button `text` object. Maximum length is 75 characters. | Optional |

> **How Repzo Chat differs from Slack**
>
> - `agent_prompt`, `agent_prompt_display` and `visible_to_user_ids` aren't supported: the button shows to everyone and always sends `block_actions`.
> - A `url` that isn't `http` or `https` is ignored and reported as a warning.
> - Buttons also work in card blocks and data table action cells; both are Repzo-rendered blocks, so check the block pages for their limits.

## Examples

### Buttons in an actions block

```json
{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Quote Q-1042* for *Northwind Traders* is waiting for your approval.\nTotal: *$18,400* · 12 seats · annual billing"
      }
    },
    {
      "type": "actions",
      "block_id": "quote_q1042",
      "elements": [
        {
          "type": "button",
          "action_id": "approve_quote",
          "text": {
            "type": "plain_text",
            "text": "Approve"
          },
          "style": "primary",
          "value": "Q-1042"
        },
        {
          "type": "button",
          "action_id": "request_changes",
          "text": {
            "type": "plain_text",
            "text": "Request changes"
          },
          "value": "Q-1042"
        },
        {
          "type": "button",
          "action_id": "open_quote",
          "text": {
            "type": "plain_text",
            "text": "View quote"
          },
          "url": "https://example.com/quotes/Q-1042"
        }
      ]
    }
  ]
}
```

### A section with a button that asks for confirmation

```json
{
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Subscription *SUB-311* for *Contoso Clinics* renews on 1 December. Cancel it before then?"
      },
      "accessory": {
        "type": "button",
        "action_id": "cancel_subscription",
        "text": {
          "type": "plain_text",
          "text": "Cancel renewal"
        },
        "style": "danger",
        "value": "SUB-311",
        "confirm": {
          "title": {
            "type": "plain_text",
            "text": "Cancel the renewal?"
          },
          "text": {
            "type": "plain_text",
            "text": "Contoso Clinics will keep access until 30 November."
          },
          "confirm": {
            "type": "plain_text",
            "text": "Cancel renewal"
          },
          "deny": {
            "type": "plain_text",
            "text": "Keep it"
          },
          "style": "danger"
        }
      }
    }
  ]
}
```

## Related

- [Block elements](https://workstation.repzo.com/docs/developers/block-kit/elements)
- [Block Kit overview](https://workstation.repzo.com/docs/developers/block-kit)