{"record":{"id":"fbfd418346e38feb","repo":"angular/components","slug":"value-must-be-an-array-in-multiple-selection-mode","errorCode":null,"errorMessage":"Value must be an array in multiple-selection mode.","messagePattern":"Value must be an array in multiple-selection mode\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/material/button-toggle/button-toggle.ts","lineNumber":481,"sourceCode":"      }\n    }\n\n    return null;\n  }\n\n  /** Updates the selection state of the toggles in the group based on a value. */\n  private _setSelectionByValue(value: any | any[]) {\n    this._rawValue = value;\n\n    if (!this._buttonToggles) {\n      return;\n    }\n\n    const toggles = this._buttonToggles.toArray();\n\n    if (this.multiple && value) {\n      if (!Array.isArray(value) && (typeof ngDevMode === 'undefined' || ngDevMode)) {\n        throw Error('Value must be an array in multiple-selection mode.');\n      }\n\n      this._clearSelection();\n      value.forEach((currentValue: any) => this._selectValue(currentValue, toggles));\n    } else {\n      this._clearSelection();\n      this._selectValue(value, toggles);\n    }\n\n    // In single selection mode we need at least one enabled toggle to always be focusable.\n    if (!this.multiple && toggles.every(toggle => toggle.tabIndex === -1)) {\n      for (const toggle of toggles) {\n        if (!toggle.disabled) {\n          toggle.tabIndex = 0;\n          break;\n        }\n      }\n    }","sourceCodeStart":463,"sourceCodeEnd":499,"githubUrl":"https://github.com/angular/components/blob/0411926e7d8ae06b32236ec1048a888cfad5abf2/src/material/button-toggle/button-toggle.ts#L463-L499","documentation":"MatButtonToggleGroup with multiple=true expects its value binding to be an array of selected toggle values. When _setSelectionByValue runs (via the group's value setter) and multiple is enabled, a non-array truthy value cannot be mapped onto individual toggles, so the library throws in dev mode.","triggerScenarios":"Binding [value] on a <mat-button-toggle-group multiple> to a non-array value (string, number, object), or programmatically setting group.value = 'foo' while multiple is true.","commonSituations":"Form controls typed as single-value (FormControl<string>) attached to a multiple group; switching a group from single to multiple selection without changing the value shape; server data returning a single value instead of an array.","solutions":["Provide an array as the value: [value]=\"['a','b']\" or FormControl with an array value.","Type the form control as FormControl<string[]> when using multiple.","If single selection is intended, remove the multiple attribute.","Guard initial data so async-loaded values default to [] instead of a scalar or undefined-shaped scalar."],"exampleFix":"// before\nctrl = new FormControl('java');\n<mat-button-toggle-group [formControl]=\"ctrl\" multiple>\n// after\nctrl = new FormControl(['java']);\n<mat-button-toggle-group [formControl]=\"ctrl\" multiple>","handlingStrategy":"type-guard","validationCode":"const value = group.value;\nif (group.multiple && !Array.isArray(value)) {\n  throw new TypeError('multiple mat-button-toggle-group requires array value');\n}","typeGuard":"function isArrayValue(v: unknown): v is any[] {\n  return Array.isArray(v);\n}","tryCatchPattern":"try {\n  group.value = selected as string[];\n} catch (e) {\n  if (e instanceof Error && e.message.includes('must be an array in multiple-selection mode')) {\n    group.value = Array.isArray(selected) ? selected : [selected];\n  } else { throw e; }\n}","preventionTips":["Type multiple group form controls as FormControl<string[]>.","Initialize multiple group values with [] not null scalars.","Normalize server payloads to arrays before binding."],"tags":["angular-material","button-toggle","multiple-selection","value-type"],"backgroundTag":"value-must-be-array","analyzedSha":"0411926e7d8ae06b32236ec1048a888cfad5abf2","analyzedAt":"2026-08-31T11:58:23.400Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}