CheckboxItem

A question item that allows the respondent to select one or more checkboxes, as well as an
optional "other" field. Items are created or accessed from a `https://developers.google.com/apps-script/reference/forms/form` using methods such as
`https://developers.google.com/apps-script/reference/forms/form#addCheckboxItem()`. When used in a quiz, these items are autograded.

```javascript
// Open a form by ID and add a new checkbox item.
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
const item = form.addCheckboxItem();
item.setTitle('What condiments would you like on your hot dog?')
    .setChoices([
      item.createChoice('Ketchup'),
      item.createChoice('Mustard'),
      item.createChoice('Relish'),
    ])
    .showOtherOption(true);
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#clearValidation()` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Removes any data validation for this checkbox item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#createChoice(String)` | `https://developers.google.com/apps-script/reference/forms/choice` | Creates a new choice. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#createChoice(String,Boolean)` | `https://developers.google.com/apps-script/reference/forms/choice` | Creates a new choice. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#createResponse(String)` | `https://developers.google.com/apps-script/reference/forms/item-response` | Creates a new `https://developers.google.com/apps-script/reference/forms/item-response` for this checkbox item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#duplicate()` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Creates a copy of this item and appends it to the end of the form. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getChoices()` | `https://developers.google.com/apps-script/reference/forms/choice` | Gets all choices for an item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getFeedbackForCorrect()` | `https://developers.google.com/apps-script/reference/forms/quiz-feedback|null` | Returns the feedback that is shown to respondents when they respond correctly to a question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getFeedbackForIncorrect()` | `https://developers.google.com/apps-script/reference/forms/quiz-feedback|null` | Returns the feedback that is shown to respondents when they respond incorrectly to a question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getHelpText()` | `String` | Gets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getId()` | `Integer` | Gets the item's unique identifier. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getIndex()` | `Integer` | Gets the index of the item among all the items in the form. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getPoints()` | `Integer` | Returns the point value of a gradeable item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getTitle()` | `String` | Gets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#getType()` | `https://developers.google.com/apps-script/reference/forms/item-type` | Gets the item's type, represented as an `https://developers.google.com/apps-script/reference/forms/item-type`. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#hasOtherOption()` | `Boolean` | Determines whether the item has an "other" option. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#isRequired()` | `Boolean` | Determines whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setChoiceValues(String)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets the choices for an item from an array of strings. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setChoices(Choice)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets an array of choices for an item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setFeedbackForCorrect(QuizFeedback)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets the feedback to be shown to respondents when they respond correctly to a question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setFeedbackForIncorrect(QuizFeedback)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets the feedback to be shown to respondents when they respond incorrectly to a question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setHelpText(String)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setPoints(Integer)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets the number of points a gradeable item is worth. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setRequired(Boolean)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setTitle(String)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`). |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#setValidation(CheckboxValidation)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets the data validation for this checkbox item. |
| `https://developers.google.com/apps-script/reference/forms/checkbox-item#showOtherOption(Boolean)` | `https://developers.google.com/apps-script/reference/forms/checkbox-item#` | Sets whether the item has an "other" option. |

## Detailed documentation

### `clearValidation()`

Removes any data validation for this checkbox item.

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `createChoice(value)`

Creates a new choice.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | the choice's value, which respondents see as a label when viewing the form |

#### Return


`https://developers.google.com/apps-script/reference/forms/choice` --- the new choice

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `createChoice(value, isCorrect)`

Creates a new choice.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | the choice's value, which respondents see as a label when viewing the form |
| `isCorrect` | `Boolean` | whether the choice is a correct answer |

#### Return


`https://developers.google.com/apps-script/reference/forms/choice` --- the new choice

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `createResponse(responses)`

Creates a new `https://developers.google.com/apps-script/reference/forms/item-response` for this checkbox item. The argument `responses` is a
`String[]` array containing values that need to be checked. Throws an exception if any
value does not match a valid choice for this item, unless `https://developers.google.com/apps-script/reference/forms/checkbox-item#showOtherOption(Boolean)` is set to `true`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `responses` | `String[]` | an array of valid answers for this multiple-choice item |

#### Return


`https://developers.google.com/apps-script/reference/forms/item-response` --- the item response

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `duplicate()`

Creates a copy of this item and appends it to the end of the form.

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- a duplicate of this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getChoices()`

Gets all choices for an item.

#### Return


`https://developers.google.com/apps-script/reference/forms/choice` --- an array of choices

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getFeedbackForCorrect()`

Returns the feedback that is shown to respondents when they respond correctly to a question.

#### Return


`https://developers.google.com/apps-script/reference/forms/quiz-feedback|null` --- the feedback, if any.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getFeedbackForIncorrect()`

Returns the feedback that is shown to respondents when they respond incorrectly to a question.

#### Return


`https://developers.google.com/apps-script/reference/forms/quiz-feedback|null` --- the feedback, if any.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getHelpText()`

Gets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Return


`String` --- the item's help text or description text

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getId()`

Gets the item's unique identifier.

#### Return


`Integer` --- the item's ID

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getIndex()`

Gets the index of the item among all the items in the form.

#### Return


`Integer` --- the index of the item

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getPoints()`

Returns the point value of a gradeable item.

#### Return


`Integer` --- the number of points a question is worth.

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getTitle()`

Gets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Return


`String` --- the item's title or header text

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `getType()`

Gets the item's type, represented as an `https://developers.google.com/apps-script/reference/forms/item-type`.

#### Return


`https://developers.google.com/apps-script/reference/forms/item-type` --- the item's type

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `hasOtherOption()`

Determines whether the item has an "other" option.

#### Return


`Boolean` --- `true` if the item has an "other" option; `false` if not

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `isRequired()`

Determines whether the respondent must answer the question.

#### Return


`Boolean` --- whether the respondent must answer the question

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setChoiceValues(values)`

Sets the choices for an item from an array of strings. Throws an exception if the given array
is empty.

```javascript
// Open a form by ID and add a new list item.
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
const item = form.addListItem();
item.setTitle('Do you prefer cats or dogs?');
item.setChoiceValues(['Dogs', 'Cats']);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `values` | `String[]` | the array of choice values, which respondents see as labels when viewing the form |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setChoices(choices)`

Sets an array of choices for an item. Throws an exception if the given array is empty or
contains a `null` element.

```javascript
// Open a form by ID and add a new list item.
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
const item = form.addListItem();
item.setTitle('Do you prefer cats or dogs?');
item.setChoices([item.createChoice('Cats'), item.createChoice('Dogs')]);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `choices` | `https://developers.google.com/apps-script/reference/forms/choice` | an array of choices |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Throws


[`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) --- if the given array is `null`, empty, or contains a `null` element

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setFeedbackForCorrect(feedback)`

Sets the feedback to be shown to respondents when they respond correctly to a question.

```javascript
// Open a form by ID and add a new list item.
const form = FormApp.openById('1234567890abcdefghijklmnopqrstuvwxyz');
const item = form.addListItem();
item.setTitle('Do you prefer cats or dogs?');
// Set "Dogs" as the correct answer to this question.
item.setChoices([
  item.createChoice('Dogs', true),
  item.createChoice('Cats', false),
]);
// Add feedback which will be shown for correct responses; ie "Dogs".
item.setFeedbackForCorrect(
    FormApp.createFeedback().setText('Dogs rule, cats drool.').build(),
);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `feedback` | `https://developers.google.com/apps-script/reference/forms/quiz-feedback` | the new feedback. A null value will clear the feedback. |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setFeedbackForIncorrect(feedback)`

Sets the feedback to be shown to respondents when they respond incorrectly to a question.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `feedback` | `https://developers.google.com/apps-script/reference/forms/quiz-feedback` | the new feedback |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setHelpText(text)`

Sets the item's help text (sometimes called description text for layout items like `https://developers.google.com/apps-script/reference/forms/image-item`, `https://developers.google.com/apps-script/reference/forms/page-break-item`, and `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `text` | `String` | the new help text |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setPoints(points)`

Sets the number of points a gradeable item is worth. The default for new items is 0.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `points` | `Integer` | the number of a points a question item is worth |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setRequired(enabled)`

Sets whether the respondent must answer the question.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `enabled` | `Boolean` | whether the respondent must answer the question |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- the current item (for chaining)

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setTitle(title)`

Sets the item's title (sometimes called header text, in the case of a `https://developers.google.com/apps-script/reference/forms/section-header-item`).

#### Parameters

| Name | Type | Description |
|---|---|---|
| `title` | `String` | the new title or header text |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `setValidation(validation)`

Sets the data validation for this checkbox item. Passing in null or a validation without any
require functions called will remove any prior validation.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `validation` | `https://developers.google.com/apps-script/reference/forms/checkbox-validation` | a CheckboxValidation to apply to this item. |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`

*** ** * ** ***

### `showOtherOption(enabled)`

Sets whether the item has an "other" option. The default for a new `https://developers.google.com/apps-script/reference/forms/checkbox-item#` or
`https://developers.google.com/apps-script/reference/forms/multiple-choice-item` is `false`.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `enabled` | `Boolean` | `true` if the item has an "other" option; `false` if not |

#### Return


`https://developers.google.com/apps-script/reference/forms/checkbox-item#` --- this `https://developers.google.com/apps-script/reference/forms/checkbox-item#`, for chaining

#### Authorization

Scripts that use this method require authorization with one or more of the following [scopes](https://developers.google.com/apps-script/concepts/scopes#setting_explicit_scopes):

- `https://www.googleapis.com/auth/forms.currentonly`
- `https://www.googleapis.com/auth/forms`