Class CheckboxItem

  • CheckboxItem allows respondents to select one or more checkboxes with an optional "other" field.

  • You can add a new checkbox item to a form using form.addCheckboxItem().

  • Methods are available to manage choices, feedback, help text, and validation for the checkbox item.

  • You can set the title and options for the checkbox item using methods like setTitle() and setChoices().

  • Checkbox items can be set as required and configured to show an "other" option.
CheckboxItem

A question item that allows the respondent to select one or more checkboxes, as well as an optional "other" field. Items can be accessed or created from a Form. When used in a quiz, these items are autograded. 

// 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

MethodReturn typeBrief description
clearValidation()CheckboxItemRemoves any data validation for this checkbox item.
createChoice(value)ChoiceCreates a new choice.
createChoice(value, isCorrect)ChoiceCreates a new choice.
createResponse(responses)ItemResponseCreates a new ItemResponse for this checkbox item.
duplicate()CheckboxItemCreates a copy of this item and appends it to the end of the form.
getChoices()Choice[]Gets all choices for an item.
getFeedbackForCorrect()QuizFeedbackReturns the feedback that is shown to respondents when they respond correctly to a question.
getFeedbackForIncorrect()QuizFeedbackReturns the feedback that is shown to respondents when they respond incorrectly to a question.
getHelpText()StringGets the item's help text (sometimes called description text for layout items like ImageItems, PageBreakItems, and SectionHeaderItems).
getId()IntegerGets the item's unique identifier.
getIndex()IntegerGets the index of the item among all the items in the form.
getPoints()IntegerReturns the point value of a gradeable item.
getTitle()StringGets the item's title (sometimes called header text, in the case of a SectionHeaderItem).
getType()ItemTypeGets the item's type, represented as an ItemType.
hasOtherOption()BooleanDetermines whether the item has an "other" option.
isRequired()BooleanDetermines whether the respondent must answer the question.
setChoiceValues(values)CheckboxItemSets the choices for an item from an array of strings.
setChoices(choices)CheckboxItemSets an array of choices for an item.
setFeedbackForCorrect(feedback)CheckboxItemSets the feedback to be shown to respondents when they respond correctly to a question.
setFeedbackForIncorrect(feedback)CheckboxItemSets the feedback to be shown to respondents when they respond incorrectly to a question.
setHelpText(text)CheckboxItemSets the item's help text (sometimes called description text for layout items like ImageItems, PageBreakItems, and SectionHeaderItems).
setPoints(points)CheckboxItemSets the number of points a gradeable item is worth.
setRequired(enabled)CheckboxItemSets whether the respondent must answer the question.
setTitle(title)CheckboxItemSets the item's title (sometimes called header text, in the case of a SectionHeaderItem).
setValidation(validation)CheckboxItemSets the data validation for this checkbox item.
showOtherOption(enabled)CheckboxItemSets whether the item has an "other" option.

Detailed documentation

clearValidation()

Removes any data validation for this checkbox item.

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/forms

createChoice(value)

Creates a new choice.

Parameters

NameTypeDescription
valueStringthe choice's value, which respondents see as a label when viewing the form

Return

Choice — the new choice

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/forms

createChoice(value, isCorrect)

Creates a new choice.

Parameters

NameTypeDescription
valueStringthe choice's value, which respondents see as a label when viewing the form
isCorrectBooleanwhether the choice is a correct answer

Return

Choice — the new choice

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/forms

createResponse(responses)

Creates a new ItemResponse 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 showOtherOption(enabled) is set to true.

Parameters

NameTypeDescription
responsesString[]an array of valid answers for this multiple-choice item

Return

ItemResponse — the item response

Authorization

Scripts that use this method require authorization with one or more of the following 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

CheckboxItem — a duplicate of this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/forms

getChoices()

Gets all choices for an item.

Return

Choice[] — an array of choices

Authorization

Scripts that use this method require authorization with one or more of the following 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

QuizFeedback — the feedback, if any.

Authorization

Scripts that use this method require authorization with one or more of the following 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

QuizFeedback — the feedback, if any.

Authorization

Scripts that use this method require authorization with one or more of the following 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 ImageItems, PageBreakItems, and SectionHeaderItems).

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://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://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://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://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 SectionHeaderItem).

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://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/forms

getType()

Gets the item's type, represented as an ItemType.

Return

ItemType — the item's type

Authorization

Scripts that use this method require authorization with one or more of the following 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://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://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. 

// 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

NameTypeDescription
valuesString[]the array of choice values, which respondents see as labels when viewing the form

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following 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. 

// 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

NameTypeDescription
choicesChoice[]an array of choices

Return

CheckboxItem — this CheckboxItem, for chaining

Throws

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://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. 

// 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().setDisplayText('Dogs rule, cats drool.').build(),
);

Parameters

NameTypeDescription
feedbackQuizFeedbackthe new feedback. A null value will clear the feedback.

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following 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

NameTypeDescription
feedbackQuizFeedbackthe new feedback

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following 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 ImageItems, PageBreakItems, and SectionHeaderItems).

Parameters

NameTypeDescription
textStringthe new help text

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following 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

NameTypeDescription
pointsIntegerthe number of a points a question item is worth

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following 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

NameTypeDescription
enabledBooleanwhether the respondent must answer the question

Return

CheckboxItem — the current item (for chaining)

Authorization

Scripts that use this method require authorization with one or more of the following 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 SectionHeaderItem).

Parameters

NameTypeDescription
titleStringthe new title or header text

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following 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

NameTypeDescription
validationCheckboxValidationa CheckboxValidation to apply to this item.

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following 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 CheckboxItem or MultipleChoiceItem is false.

Parameters

NameTypeDescription
enabledBooleantrue if the item has an "other" option; false if not

Return

CheckboxItem — this CheckboxItem, for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes:

  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/forms