Grid

An organized grid to display a collection of grid items.

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

```javascript
const grid = CardService.newGrid().setTitle('My Grid').setNumColumns(2).addItem(
    CardService.newGridItem().setTitle('My item'));
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/card-service/grid#addEventAction(EventAction)` | `https://developers.google.com/apps-script/reference/card-service/widget` | Adds the event action that can be performed on the widget. |
| `https://developers.google.com/apps-script/reference/card-service/grid#addItem(GridItem)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | Adds a new grid item to the grid. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setAuthorizationAction(AuthorizationAction)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | 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/grid#setBorderStyle(BorderStyle)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | Sets the border style applied to each grid item. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setComposeAction(Action,ComposedEmailType)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | Sets an action that composes a draft email when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setId(String)` | `https://developers.google.com/apps-script/reference/card-service/widget` | Sets the unique ID assigned that's used to identify the widget to be mutated. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setNumColumns(Integer)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | The number of columns to display in the grid. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | Sets an action that executes when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickOpenLinkAction(Action)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | Sets an action that opens a URL in a tab when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setOpenLink(OpenLink)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | Sets a URL to be opened when the object is clicked. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setTitle(String)` | `https://developers.google.com/apps-script/reference/card-service/grid#` | Sets the title text of the grid. |
| `https://developers.google.com/apps-script/reference/card-service/grid#setVisibility(Visibility)` | `https://developers.google.com/apps-script/reference/card-service/widget` | Sets the visibility of the widget. |

## Detailed documentation

### `addEventAction(eventAction)`

Adds the event action that can be performed on the widget.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `eventAction` | `https://developers.google.com/apps-script/reference/card-service/event-action` | The `https://developers.google.com/apps-script/reference/card-service/event-action` to be added. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/widget` --- The Object, for chaining.

*** ** * ** ***

### `addItem(gridItem)`

Adds a new grid item to the grid.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `gridItem` | `https://developers.google.com/apps-script/reference/card-service/grid-item` | The grid item to add. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/grid#` --- 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/grid#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/grid#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/grid#` --- This object, for chaining.

*** ** * ** ***

### `setBorderStyle(borderStyle)`

Sets the border style applied to each grid item. Default is NO_BORDER.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `borderStyle` | `https://developers.google.com/apps-script/reference/card-service/border-style` | The border style to apply. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/grid#` --- 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/grid#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickOpenLinkAction(Action)`,
`https://developers.google.com/apps-script/reference/card-service/grid#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/grid#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/grid#` --- This object, for chaining.

*** ** * ** ***

### `setId(id)`

Sets the unique ID assigned that's used to identify the widget to be mutated. Widget mutation
is only supported in Add-Ons.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `id` | `String` | The id of the widget, with a limit of 64 characters and in format of \`\[a-zA-Z0-9-\]+\`. |

#### Return


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

*** ** * ** ***

### `setNumColumns(numColumns)`

The number of columns to display in the grid. If shown in the right side panel, you can display
1-2 columns and the default value is 1. If shown in a dialog, you can display 2-3 columns and
the default value is 2.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `numColumns` | `Integer` | The number of columns. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/grid#` --- 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/grid#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setAuthorizationAction(AuthorizationAction)`, or `https://developers.google.com/apps-script/reference/card-service/grid#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/grid#` --- 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/grid#setOpenLink(OpenLink)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setAuthorizationAction(AuthorizationAction)`, or
`https://developers.google.com/apps-script/reference/card-service/grid#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/grid#` --- 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/grid#setOpenLink(OpenLink)`,
`https://developers.google.com/apps-script/reference/card-service/grid#setOnClickAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setOnClickOpenLinkAction(Action)`, `https://developers.google.com/apps-script/reference/card-service/grid#setAuthorizationAction(AuthorizationAction)`,
or `https://developers.google.com/apps-script/reference/card-service/grid#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/grid#` --- This object, for chaining.

*** ** * ** ***

### `setTitle(title)`

Sets the title text of the grid. The text must be a plain string with no formatting.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | The title text. |

#### Return


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

*** ** * ** ***

### `setVisibility(visibility)`

Sets the visibility of the widget. The default value is \`VISIBLE\`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `visibility` | `https://developers.google.com/apps-script/reference/card-service/visibility` | The `https://developers.google.com/apps-script/reference/card-service/visibility` of the widget. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/widget` --- The Object, for chaining.