ListItem

A question item that allows the respondent to select one choice from a drop-down list. Items can
be accessed or created from a `https://developers.google.com/apps-script/reference/forms/form`.

```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?').setChoices([
  item.createChoice('Cats'), item.createChoice('Dogs')
]);
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/forms/list-item#createChoice(String)` | `https://developers.google.com/apps-script/reference/forms/choice` | Creates a new choice. |
| `https://developers.google.com/apps-script/reference/forms/list-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/list-item#createChoice(String,PageBreakItem)` | `https://developers.google.com/apps-script/reference/forms/choice` | Creates a new choice with a page-navigation option that jumps to a given page-break item. |
| `https://developers.google.com/apps-script/reference/forms/list-item#createChoice(String,PageNavigationType)` | `https://developers.google.com/apps-script/reference/forms/choice` | Creates a new choice with a page-navigation option. |
| `https://developers.google.com/apps-script/reference/forms/list-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 list item. |
| `https://developers.google.com/apps-script/reference/forms/list-item#duplicate()` | `https://developers.google.com/apps-script/reference/forms/list-item#` | Creates a copy of this item and appends it to the end of the form. |
| `https://developers.google.com/apps-script/reference/forms/list-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/list-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/list-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/list-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/list-item#getId()` | `Integer` | Gets the item's unique identifier. |
| `https://developers.google.com/apps-script/reference/forms/list-item#getIndex()` | `Integer` | Gets the index of the item among all the items in the form. |
| `https://developers.google.com/apps-script/reference/forms/list-item#getPoints()` | `Integer` | Returns the point value of a gradeable item. |
| `https://developers.google.com/apps-script/reference/forms/list-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/list-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/list-item#isRequired()` | `Boolean` | Determines whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/list-item#setChoiceValues(String)` | `https://developers.google.com/apps-script/reference/forms/list-item#` | Sets the choices for an item from an array of strings. |
| `https://developers.google.com/apps-script/reference/forms/list-item#setChoices(Choice)` | `https://developers.google.com/apps-script/reference/forms/list-item#` | Sets an array of choices for an item. |
| `https://developers.google.com/apps-script/reference/forms/list-item#setFeedbackForCorrect(QuizFeedback)` | `https://developers.google.com/apps-script/reference/forms/list-item#` | Sets the feedback to be shown to respondents when they respond correctly to a question. |
| `https://developers.google.com/apps-script/reference/forms/list-item#setFeedbackForIncorrect(QuizFeedback)` | `https://developers.google.com/apps-script/reference/forms/list-item#` | Sets the feedback to be shown to respondents when they respond incorrectly to a question. |
| `https://developers.google.com/apps-script/reference/forms/list-item#setHelpText(String)` | `https://developers.google.com/apps-script/reference/forms/list-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/list-item#setPoints(Integer)` | `https://developers.google.com/apps-script/reference/forms/list-item#` | Sets the number of points a gradeable item is worth. |
| `https://developers.google.com/apps-script/reference/forms/list-item#setRequired(Boolean)` | `https://developers.google.com/apps-script/reference/forms/list-item#` | Sets whether the respondent must answer the question. |
| `https://developers.google.com/apps-script/reference/forms/list-item#setTitle(String)` | `https://developers.google.com/apps-script/reference/forms/list-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`). |

## Detailed documentation

### `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`

*** ** * ** ***

### `createChoice(value, navigationItem)`

Creates a new choice with a page-navigation option that jumps to a given page-break item. This
is equivalent to `https://developers.google.com/apps-script/reference/forms/list-item#createChoice(String,PageNavigationType)` with `navigationType` set to `FormApp.PageNavigationType.GO_TO_PAGE`. Choices that use page
navigation cannot be combined in the same item with choices that do not use page navigation.

The page navigation occurs after the respondent completes a page that contains the option,
and only if the respondent chose that option. If the respondent chose multiple options with
page-navigation instructions on the same page, only the last navigation option has any effect.
Page navigation also has no effect on the last page of a form.

Note that using page navigation on an item hardcodes the routing, meaning `showOtherOption(true)` shouldn't be used concurrently.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | the choice's value, which respondents see as a label when viewing the form |
| `navigationItem` | `https://developers.google.com/apps-script/reference/forms/page-break-item` | the item to navigate to |

#### 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, navigationType)`

Creates a new choice with a page-navigation option. Choices that use page navigation cannot be
combined in the same item with choices that do not use page navigation.

The page navigation occurs after the respondent completes a page that contains the option,
and only if the respondent chose that option. If the respondent chose multiple options with
page-navigation instructions on the same page, only the last navigation option has any effect.
Page navigation also has no effect on the last page of a form.

Note that using page navigation on an item hardcodes the routing, meaning `showOtherOption(true)` shouldn't be used concurrently.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | the choice's value, which respondents see as a label when viewing the form |
| `navigationType` | `https://developers.google.com/apps-script/reference/forms/page-navigation-type` | the choice's navigation type |

#### 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(response)`

Creates a new `https://developers.google.com/apps-script/reference/forms/item-response` for this list item. Throws an exception if the `response` argument does not match a valid choice for this item.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `response` | `String` | a valid answer for this list 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/list-item#` --- a duplicate of this `https://developers.google.com/apps-script/reference/forms/list-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`

*** ** * ** ***

### `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/list-item#` --- this `https://developers.google.com/apps-script/reference/forms/list-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/list-item#` --- this `https://developers.google.com/apps-script/reference/forms/list-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/list-item#` --- this `https://developers.google.com/apps-script/reference/forms/list-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/list-item#` --- this `https://developers.google.com/apps-script/reference/forms/list-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/list-item#` --- this `https://developers.google.com/apps-script/reference/forms/list-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/list-item#` --- this `https://developers.google.com/apps-script/reference/forms/list-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/list-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/list-item#` --- this `https://developers.google.com/apps-script/reference/forms/list-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`