TextButton

A `https://developers.google.com/apps-script/reference/card-service/text-button#` with a text label. You can set the background color and deactivate the button
when needed.

Available for Google Workspace add-ons and Google Chat apps.

```javascript
const textButton = CardService.newTextButton()
                       .setText('Open Link')
                       .setOpenLink(CardService.newOpenLink().setUrl(
                           'https://www.google.com'));
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/card-service/text-button#setAltText(String)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets the alternative text of the button for accessibility. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setAuthorizationAction(AuthorizationAction)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets an authorization action that opens a URL to the authorization flow when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setBackgroundColor(String)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets the background color for `https://developers.google.com/apps-script/reference/card-service/text-button-style#FILLED` button. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setComposeAction(Action,ComposedEmailType)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets an action that composes a draft email when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setDisabled(Boolean)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets whether the button is disabled. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setIcon(Icon)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets a predefined `https://developers.google.com/apps-script/reference/card-service/icon` to display on the button. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setIconUrl(String)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets the URL of an image to use as this button's icon. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setMaterialIcon(MaterialIcon)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets the material design icon. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets an action that executes when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickOpenLinkAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets an action that opens a URL in a tab when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setOpenLink(OpenLink)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets a URL to be opened when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setOverflowMenu(OverflowMenu)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets a pop-up menu to be opened when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setText(String)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets the text that displays on the button. |
| `https://developers.google.com/apps-script/reference/card-service/text-button#setTextButtonStyle(TextButtonStyle)` | `https://developers.google.com/apps-script/reference/card-service/text-button#` | Sets the button style. |

## Detailed documentation

### `setAltText(altText)`

Sets the alternative text of the button for accessibility. If unset, defaults to the text that
displays on the button.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `altText` | `String` | The alternative text to assign to this button. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setAuthorizationAction(action)`

Sets an authorization action that opens a URL to the authorization flow when the object is
clicked. This opens the URL in a new window. When the user finishes the authorization flow and
returns to the application, the add-on reloads.

A UI object can only have one of `https://developers.google.com/apps-script/reference/card-service/text-button#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/text-button#setComposeAction(Action,ComposedEmailType)` set.

```javascript
// ...

const action = CardService.newAuthorizationAction().setAuthorizationUrl('url');
CardService.newTextButton().setText('Authorize').setAuthorizationAction(action);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/authorization-action` | The object that specifies the authorization action to take when this element is clicked. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setBackgroundColor(backgroundColor)`

Sets the background color for `https://developers.google.com/apps-script/reference/card-service/text-button-style#FILLED` button. If unset for a `https://developers.google.com/apps-script/reference/card-service/text-button-style#FILLED` button, the button uses the secondary color defined in the add-on [manifest](https://developers.google.com/gmail/add-ons/concepts/manifests#manifest_structure_for_gmail_add-ons).
This method is a no-op for `https://developers.google.com/apps-script/reference/card-service/text-button-style#OUTLINED` buttons.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `backgroundColor` | `String` | The color in #rgb format. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setComposeAction(action, composedEmailType)`

Sets an action that composes a draft email when the object is clicked. A UI object can only
have one of `https://developers.google.com/apps-script/reference/card-service/text-button#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickOpenLinkAction(Action)`,
`https://developers.google.com/apps-script/reference/card-service/text-button#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/text-button#setComposeAction(Action,ComposedEmailType)` set.

The `https://developers.google.com/apps-script/reference/card-service/action` parameter must specify a callback function that returns a `https://developers.google.com/apps-script/reference/card-service/compose-action-response` object configured using `https://developers.google.com/apps-script/reference/card-service/compose-action-response-builder#setGmailDraft(GmailDraft)`.


> [!NOTE]
> **Note** : This method doesn't set a **compose action** that is used to [extend the compose UI](https://developers.google.com/gmail/add-ons/how-tos/extending-compose-ui). Rather, this method connects this UI element to an `https://developers.google.com/apps-script/reference/card-service/action` that [composes draft messages](https://developers.google.com/gmail/add-ons/how-tos/compose) in Apps Script that are opened in Gmail when the action completes.

<br />

```javascript
// ...

const action = CardService.newAction().setFunctionName('composeEmailCallback');
CardService.newTextButton()
    .setText('Compose Email')
    .setComposeAction(action, CardService.ComposedEmailType.REPLY_AS_DRAFT);

// ...

function composeEmailCallback(e) {
  const thread = GmailApp.getThreadById(e.threadId);
  const draft = thread.createDraftReply('This is a reply');
  return CardService.newComposeActionResponseBuilder()
      .setGmailDraft(draft)
      .build();
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/action` | The object that specifies the compose action to take when this element is clicked. |
| `composedEmailType` | `https://developers.google.com/apps-script/reference/card-service/composed-email-type` | An enum value that specifies whether the composed draft is a standalone or reply draft. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setDisabled(disabled)`

Sets whether the button is disabled. A disabled button is greyed out and cannot be clicked.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `disabled` | `Boolean` | The disabled state. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setIcon(icon)`

Sets a predefined `https://developers.google.com/apps-script/reference/card-service/icon` to display on the button. Either this or `https://developers.google.com/apps-script/reference/card-service/text-button#setIconUrl(String)`
must be used to define the button image.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `icon` | `https://developers.google.com/apps-script/reference/card-service/icon` | One of the predefined `https://developers.google.com/apps-script/reference/card-service/icon` values. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setIconUrl(url)`

Sets the URL of an image to use as this button's icon. Either this or `https://developers.google.com/apps-script/reference/card-service/text-button#setIcon(Icon)` must be
used to define the button image.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `url` | `String` | The URL address of a hosted image to use as this button's icon. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setMaterialIcon(icon)`

Sets the material design icon.

```javascript
const textButton = CardService.newTextButton().setMaterialIcon(
    CardService.newMaterialIcon().setName('search'),
);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `icon` | `https://developers.google.com/apps-script/reference/card-service/material-icon` | The material design icon. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setOnClickAction(action)`

Sets an action that executes when the object is clicked. A UI object can only have one of
`https://developers.google.com/apps-script/reference/card-service/text-button#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/text-button#setComposeAction(Action,ComposedEmailType)` set.

The `https://developers.google.com/apps-script/reference/card-service/action` parameter must specify a callback function that returns a `https://developers.google.com/apps-script/reference/card-service/action-response` object.

```javascript
// ...

const action = CardService.newAction().setFunctionName('notificationCallback');
CardService.newTextButton()
    .setText('Create notification')
    .setOnClickAction(action);

// ...

function notificationCallback() {
  return CardService.newActionResponseBuilder()
      .setNotification(
          CardService.newNotification().setText('Some info to display to user'),
          )
      .build();
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/action` | The action to take when this element is clicked. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setOnClickOpenLinkAction(action)`

Sets an action that opens a URL in a tab when the object is clicked. Use this function when the
URL needs to be built or when you need to take other actions in addition to creating the `https://developers.google.com/apps-script/reference/card-service/open-link` object. A UI object can only have one of `https://developers.google.com/apps-script/reference/card-service/text-button#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setAuthorizationAction(AuthorizationAction)`, or
`https://developers.google.com/apps-script/reference/card-service/text-button#setComposeAction(Action,ComposedEmailType)` set.

The `https://developers.google.com/apps-script/reference/card-service/action` parameter must specify a callback function that returns a `https://developers.google.com/apps-script/reference/card-service/action-response` object configured using `https://developers.google.com/apps-script/reference/card-service/action-response-builder#setOpenLink(OpenLink)`.

```javascript
// ...

const action = CardService.newAction().setFunctionName('openLinkCallback');
CardService.newTextButton()
    .setText('Open Link')
    .setOnClickOpenLinkAction(action);

// ...

function openLinkCallback() {
  return CardService.newActionResponseBuilder()
      .setOpenLink(CardService.newOpenLink().setUrl('https://www.google.com'))
      .build();
}
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `action` | `https://developers.google.com/apps-script/reference/card-service/action` | The object that specifies the open link action to take when this element is clicked. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setOpenLink(openLink)`

Sets a URL to be opened when the object is clicked. Use this function when the URL is already
known and only needs to be opened. A UI object can only have one of `https://developers.google.com/apps-script/reference/card-service/text-button#setOpenLink(OpenLink)`,
`https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/text-button#setAuthorizationAction(AuthorizationAction)`,
or `https://developers.google.com/apps-script/reference/card-service/text-button#setComposeAction(Action,ComposedEmailType)` set.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `openLink` | `https://developers.google.com/apps-script/reference/card-service/open-link` | An `https://developers.google.com/apps-script/reference/card-service/open-link` object describing the URL to open. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setOverflowMenu(menu)`

Sets a pop-up menu to be opened when the object is clicked. Each item in the menu can specify
an action to be triggered when clicked. Nested menus are not supported, actions for menu items
should not specify an overflow menu.

Available for Google Chat apps. In developer preview for Google Workspace add-ons.


> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features.

<br />

```javascript
const overflowMenuItem =
    CardService.newOverflowMenuItem()
        .setStartIcon(
            CardService.newIconImage().setIconUrl(
                'https://www.google.com/images/branding/googleg/1x/googleg_standard_color_64dp.png',
                ),
            )
        .setText('Open Link')
        .setOpenLink(
            CardService.newOpenLink().setUrl('https://www.google.com'));

const overflowMenu =
    CardService.newOverflowMenu().addMenuItem(overflowMenuItem).build();
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `menu` | `https://developers.google.com/apps-script/reference/card-service/overflow-menu` | The object that specifies the overflow menu to display when this element is clicked. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setText(text)`

Sets the text that displays on the button.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | The text that appears on the button. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.

*** ** * ** ***

### `setTextButtonStyle(textButtonStyle)`

Sets the button style. If unset, it defaults to `https://developers.google.com/apps-script/reference/card-service/text-button-style#OUTLINED` button.

```javascript
const button =
    CardService.newTextButton()
        .setText('Filled')
        .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
        .setOpenLink(CardService.newOpenLink().setUrl('www.google.com'));
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `textButtonStyle` | `https://developers.google.com/apps-script/reference/card-service/text-button-style` | The button style. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/text-button#` --- This object, for chaining.