Multi-select ComboBox as a form field: validation, isRequired, and fully controlled mode

[BMCwebdev]

We're building a design system on top of React Aria Components and are excited about the new multi-select ComboBox support in v1.16.0. We've successfully implemented the basic rendering using selectionMode="multiple" with ComboBoxValue and TagGroup to display selected items as tags — this all works great.

However, we're running into issues when trying to use the multi-select ComboBox as a proper form field with validation. We'd love guidance from the team on the intended patterns.

We've now dug through the published v1.16.0 source and confirmed a few details, which we've summarized below so this discussion can stay concrete.

For context, our design-system wrapper already composes the control in the same general way as the docs example: React Aria ComboBox + Input + popover/listbox + ComboBoxValue + TagGroup. So far, these issues do not appear to come from replacing Input with a custom field implementation.

Questions

1. isRequired validation

When isRequired is set on a multi-select ComboBox inside a <Form>, submitting with items selected still triggers a required validation error.

What we found: The required attribute is set on the visible text <input>, but in multi-select mode the input text is always empty (selections are rendered as tags via ComboBoxValue). So the native valueMissing constraint fires even when items are selected.

Additionally, useComboBoxState passes null as the validation value when displayValue is an empty array (line ~353 of useComboBoxState.ts):

value: useMemo(() =>
  Array.isArray(displayValue) && displayValue.length === 0
    ? null
    : { inputValue, value: displayValue, selectedKey },
  ...
)

This causes useFormValidationState to skip the validate function entirely (if (!validate || value == null) { return null; }), so custom validation can't catch the empty case either.

Question: Is there a recommended way to use isRequired with a multi-select ComboBox? Should we expect this to work out of the box, or is validation for multi-select still in progress?

2. Custom validation (validate prop)

Given the null-skip behavior above, the validate function is never called when zero items are selected. It does get called when items are selected, so we can validate "at least N items" when N > 0, but not "at least 1 item."

Question: Is there a recommended pattern for custom validation with multi-select ComboBox? For example, enforcing minimum/maximum selection counts?

3. Server-side validation

We use React Aria's server validation pattern (validationErrors on <Form>) for our form components.

What we found: ComboBox appears to render one hidden input per selected key when name is set and formValue="key" is used. When no items are selected, it renders a single hidden input with an empty string. This suggests multi-select submission should use formData.getAll(name) rather than formData.get(name).

useFormValidationState also appears to look up server errors by name, even for ComboBox.

Question: Is this the intended submission/validation model for multi-select ComboBox? If so, should validationErrors be expected to work out of the box with name in the multi-select case, and should consumers always use getAll(name) server-side?

4. Fully controlled mode (inputValue + value)

When we control both inputValue and value, the input text is always blank after selecting an item (which makes sense for multi-select — you wouldn't want the input to show a single selected item's text). But we want to confirm this is the intended behavior.

Question: In fully controlled multi-select mode, is inputValue expected to remain empty / be cleared after each selection? Is there anything we need to handle differently compared to single-select fully controlled mode?

5. Async data + validation coupling

In the async case, items usually reflect only the current query. After selecting an item, many implementations clear inputValue, which can immediately empty the fetched collection. At that point, the field may still have selected keys and should be considered valid, but the visible input text is empty and the current option list may also be empty.

This seems to reinforce that validation for multi-select should be based on the selected keys, not the input text or the currently loaded async collection.

Question: Is that the intended model for async multi-select as well? If the selected item objects are no longer present in the current async collection after the query changes, should consumers keep their own cache for rendering tags and validation UI, or is ComboBox expected to preserve enough selected item data internally?

Additional finding: ComboBoxValue + TagGroup with async data

One related gotcha we hit: ComboBoxValue's render prop gives back the selected item values, but TagGroup expects items with stable keys for its collection. If the selected item objects don't include an id property themselves, passing selectedItems directly to TagGroup can fail with:

Error: Could not determine key for item

Question: Is passing selectedItems directly to TagGroup only expected to work when each selected item object already includes its own id/key property? Or is there another recommended pattern for the async case?

Environment

• react-aria-components: 1.16.0
• react-aria: 3.47.0
• react-stately: 3.45.0
• react: 19.2.3

Reproduction

Here's a minimal example that demonstrates the isRequired issue:

import { Form, ComboBox, ComboBoxValue, Input, Button, Label, FieldError } from 'react-aria-components';

const items = [
  { id: '1', name: 'Option 1' },
  { id: '2', name: 'Option 2' },
  { id: '3', name: 'Option 3' },
];

function App() {
  return (
    <Form>
      <ComboBox
        selectionMode="multiple"
        defaultItems={items}
        isRequired
      >
        <Label>Select items</Label>
        <Input />
        <ComboBoxValue>
          {/* TagGroup rendering here */}
        </ComboBoxValue>
        <FieldError />
        {/* Popover + ListBox here */}
      </ComboBox>
      <Button type="submit">Submit</Button>
    </Form>
  );
}

Steps to reproduce:

1. Open the form
2. Select one or more items from the ComboBox
3. Click Submit
4. Expected: Form submits successfully (required is satisfied)
5. Actual: Required validation error appears

Thank you for any guidance! The multi-select ComboBox feature is exactly what we needed, and we'd love to fully integrate it into our form system.

[devongovett]

1. Yes, I think isRequired should apply to the hidden inputs in multi-select mode, and not to the textfield. Can you open an issue/PR for this?
2. validate isn't called when the value is empty/null in any component I don't think. The isRequired case should cover this for one item. If you want to enforce >= 2 items, you can do so with validate.
3. Yes formData.getAll makes sense here. For validation errors, I think there's only one error for the whole combobox, not a separate error for each item. Is that what you're asking?
4. Yes, the ComboBox clears after selecting an item. If you are controlling inputValue, then you may need to handle this yourself. An example might help here if you have a more specific issue.
5. I guess you mean if the selected value contains items that aren't loaded from the list yet? In that case, yes, you will need to use the keys to look up the selected values yourself because they won't be available in the selectedItems render prop value.
6. Yes, if your objects don't have an id property on them, you need to pass an id prop to the <Tag> component, same as using TagGroup or any collection component. https://react-aria.adobe.com/collections#unique-ids

[BMCwebdev]

Done! #9788

[BMCwebdev]

Thanks for all the feedback, Devon!