angular/components · error · Error

Listbox cannot have more than one selected value in single…

Error message

Listbox cannot have more than one selected value in single selection mode.

What it means

CdkListbox validates its selection model via _verifyOptionValues. In single-selection mode (multiple=false) more than one selected value is invalid, so the listbox throws. This protects the single-select invariant that the selection model should hold at most one value.

Solutions

Pass a single value, not an array: `value: 'one'` instead of `value: ['one','two']` when multiple is false.
Set `multiple` to true if users must select several values.
Before toggling multiple -> false, reset the selection to at most one value (e.g. `listbox.value = undefined` or patch the control).
Fix the data source so only one initial value is selected for single mode.

Example fix

// before
this.listbox.value = ['a', 'b']; // multiple === false
// after
this.listbox.value = 'a'; // or set multiple = true for arrays

Defensive patterns

Strategy: validation

Validate before calling

const value = control.value;
const safe = Array.isArray(value) ? value[0] : value;
if (!listbox.multiple && Array.isArray(value)) {
  control.setValue(safe);
}

Type guard

function isSingleSelectionValue(v: unknown): v is string | number | undefined {
  return v === undefined || typeof v === 'string' || typeof v === 'number';
}

Try / catch

try {
  listbox.value = candidate;
} catch (e) {
  if ((e as Error).message.includes('more than one selected value')) {
    listbox.value = Array.isArray(candidate) ? candidate[0] : candidate;
  } else { throw e; }
}

Prevention

Match the value shape to the multiple input: scalar for single, array for multiple.
Reset selection before toggling multiple at runtime.
Type the control value (e.g. FormControl<string>) to prevent arrays leaking in.
Add unit tests covering both single and multi configurations.

When it happens

Trigger: Binding [value] / form-control value to an array with more than one entry while `multiple` is false; changing multiple from true to false at runtime while several options remain selected.

Common situations: Reusing the same form control definition for both single and multi select variants; a checkbox-group-like template accidentally bound to a single-select listbox; toggling the `multiple` input without resetting the selection.

Related errors

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/39163e098c982589. Report an issue: GitHub.

Appendix: source

Thrown at src/cdk/listbox/listbox.ts:1021

            console.warn(`Found multiple CdkOption with the same value`, {
              option1: option.element,
              option2: duplicate.element,
            });
          }
          return;
        }
      }
    });
  }

  /** Verifies that the option values are valid. */
  private _verifyOptionValues() {
    if (this.options && (typeof ngDevMode === 'undefined' || ngDevMode)) {
      const selected = this.selectionModel.selected;
      const invalidValues = this._getInvalidOptionValues(selected);

      if (!this.multiple && selected.length > 1) {
        throw Error('Listbox cannot have more than one selected value in single selection mode.');
      }

      if (invalidValues.length) {
        throw Error('Listbox has selected values that do not match any of its options.');
      }
    }
  }

  /**
   * Coerces a value into an array representing a listbox selection.
   * @param value The value to coerce
   * @return An array
   */
  private _coerceValue(value: readonly T[]) {
    return value == null ? [] : coerceArray(value);
  }

  /**

View on GitHub (pinned to 0411926e7d)