InputfieldSelect

addOption($value, $label = null, $attributes = null)

Add a single option. If $label is omitted, the value is used as the label. Returns $this.

$f->addOption('red', 'Red');
$f->addOption('none'); // value and label are both 'none'

To add a disabled option, pass ['disabled' => 'disabled'] as attributes:

$f->addOption('tbd', 'To be decided', ['disabled' => 'disabled']);

To pre-select an option, use val() after adding options:

$f->addOption('green', 'Green');
$f->val('green'); // pre-select green

To add an optgroup, pass the group label as $value and an array of [value => label] as $label:

$f->addOption('Warm colors', ['red' => 'Red', 'orange' => 'Orange', 'yellow' => 'Yellow']);
$f->addOption('Cool colors', ['blue' => 'Blue', 'green' => 'Green']);

To add a separator (horizontal rule), pass a string of three or more dashes 3.0.236+:

$f->addOption('---');

addOptions(array $options, $assoc = true)

Add multiple options at once. By default, treats keys as values and values as labels.

$f->addOptions([
    'red'   => 'Red',
    'green' => 'Green',
    'blue'  => 'Blue',
]);

When $assoc is false, the array values are used for both value and label (keys ignored):

$f->addOptions(['Red', 'Green', 'Blue'], false);
// adds options where value and label are both 'Red', 'Green', 'Blue'

setOptions(array $options, $assoc = true)

Replace all existing options with the given array. Same signature as addOptions().

$f->setOptions(['a' => 'Option A', 'b' => 'Option B']);

addOptionsString($value)

Add options from a multi-line string. One option per line. Useful when options come from a textarea config field or a text block.

$f->addOptionsString("
Red
Green
Blue
");

With separate values and labels, a blank option, and 'Green' pre-selected:

$f->addOptionsString("
=
r=Red
+g=Green
b=Blue
");

Options string format:

Optgroups: indent options with 3 or more spaces after a non-indented line:

Warm colors
   r=Red
   o=Orange
Cool colors
   b=Blue
   g=Green

removeOption($value)

Remove an option by its value. Returns $this.

$f->removeOption('red');

replaceOption($oldValue, $newValue, $newLabel = null, $newAttributes = null)

Replace an existing option, preserving its position in the list. Returns true if found and replaced, false if not found.

$f->replaceOption('tbd', 'pending', 'Pending');

insertOptionsBefore(array $options, $existingValue = null)

Insert new options before an existing option, or prepend to the beginning if $existingValue is omitted. Returns $this.

$f->insertOptionsBefore(['none' => 'None'], 'red');
// inserts 'none' before 'red'

insertOptionsAfter(array $options, $existingValue = null)

Insert new options after an existing option, or append to the end if $existingValue is omitted. Returns $this.

$f->insertOptionsAfter(['other' => 'Other']);
// appends 'other' to the end

getOptions()

Returns all options as an associative array [value => label].

$options = $f->getOptions();

isOption($value)

Returns true if the given value is a valid option (including within optgroups). Separator values are never considered valid options.

if($f->isOption('red')) {
    // 'red' is available
}

isOptionSelected($value)

Returns true if the given option value is currently selected.

if($f->isOptionSelected('green')) { ... }

isOptionDisabled($value)

Returns true if the given option value has the disabled attribute set.

if($f->isOptionDisabled('tbd')) { ... }

optionLabel($key, $label = null)

Get or set the label for a given option value (default language).

// get label
$label = $f->optionLabel('red'); // 'Red'

// set label
$f->optionLabel('red', 'Dark red');

Returns the label string, or false if the option is not found.

addOptionLabel($value, $label, $language = null)

Add a translated label for an option value in a specific language 3.0.176+. If specified, $language can be a Language object, name or ID.

$f->addOptionLabel('red', 'Rojo', 'es');

optionLanguageLabel($language, $key = null, $label = null)

Low-level get/set for language-specific option labels. Accepts Language object, ID, or name string.

// set one label
$f->optionLanguageLabel('es', 'red', 'Rojo');

// set multiple labels for a language at once
$f->optionLanguageLabel('es', ['red' => 'Rojo', 'green' => 'Verde']);

// get all labels for a language
$labels = $f->optionLanguageLabel('es');

// remove all labels for a language
$f->optionLanguageLabel('es', false);

optionAttributes($key = null, $attributes = null, $append = false)

Combined get/set for option attributes. Without arguments, returns all option attributes. With $key only, returns attributes for that option. With $attributes array, sets (or appends) attributes for that option.

// get all option attributes
$all = $f->optionAttributes();

// get attributes for one option
$attrs = $f->optionAttributes('red'); // e.g. ['disabled' => 'disabled']

// set attributes for one option
$f->optionAttributes('red', ['class' => 'highlight']);

// append attributes (merge, don't replace)
$f->optionAttributes('red', ['data-hex' => '#ff0000'], true);

setOptionAttributes($key, array $attrs)

Set (replace) the entire attributes array for an option. Pass an associative array as $key to replace ALL option attributes at once.

addOptionAttributes($key, array $attrs)

Merge attributes into an option's existing attributes without replacing them.

getOptionAttributes($key = null)

Get attributes for a specific option, or all option attributes if $key is omitted.

Default value

When defaultValue is set and the field is required and currently empty, the default value is applied automatically during render() and after processInput().

$f->required = true;
$f->defaultValue = 'green';
// if no value is selected, 'green' is used

valueAddOption

When valueAddOption is true, setting a value via the API that is not already a defined option automatically adds it as an option. Applies only to values set from code — not to user-submitted input (security).

$f->valueAddOption = true;
$f->val('purple'); // 'purple' is added as an option and selected

isEmpty()

Returns true when no option is selected. The value '0' is considered empty only when '0' is not a defined option.

if($f->isEmpty()) {
    // nothing selected
}

processInput() validates all submitted values against the defined options list and silently removes any that are not present. This prevents injection of arbitrary values through manipulated form submissions.

• Value is always an array. Use $f->val(['a', 'b']) to set multiple selections.
• Blank options are silently ignored — multi-select has no concept of a "blank" selection.
• Implements InputfieldHasArrayValue. After processInput(), $f->val() returns an array of selected values.
• Source file: wire/modules/Inputfield/InputfieldSelectMultiple.module