feat(form-core): add array method field.clearValues and form.clearFieldValues

[Pascalmh]

Problem

When setting a field back to an empty array

const form = new FormApi({
  defaultValues: {
    items: [
        { firstName: "" }
    ],
  },
});

form.setFieldValue('items', []); <-- reset

items[0].firstName would still exist - when there's a validation on the firstName (on the Field-level) form.canSubmit would be false.

Solution

Adding array method field.clearValues and form.clearFieldValues

- form.setFieldValue('items', []);
+ form.clearFieldValues("items")

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 0c5b406.

Command	Status	Duration	Result
nx affected --targets=test:sherif,test:knip,tes...	✅ Succeeded	1m 35s	View ↗
nx run-many --target=build --exclude=examples/**	✅ Succeeded	22s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-04-25 12:22:47 UTC

[pkg-pr-new]

More templates

• @tanstack/form-example-angular-array
• @tanstack/form-example-angular-simple
• @tanstack/form-example-lit-simple
• @tanstack/form-example-lit-ui-libraries
• @tanstack/form-example-react-array
• @tanstack/form-example-react-compiler
• @tanstack/field-errors-from-form-validators
• @tanstack/form-example-react-large-form
• @tanstack/form-example-react-next-server-actions
• @tanstack/form-example-react-query-integration
• @tanstack/form-example-remix
• @tanstack/form-example-react-simple
• @tanstack/form-example-react-standard-schema
• @tanstack/form-example-react-tanstack-start
• @tanstack/form-example-react-ui-libraries
• @tanstack/form-example-solid-array
• @tanstack/form-example-solid-simple
• @tanstack/form-example-svelte-array
• @tanstack/form-example-svelte-simple
• @tanstack/form-example-vue-array
• @tanstack/form-example-vue-simple

@tanstack/angular-form

npm i https://pkg.pr.new/@tanstack/angular-form@1404

@tanstack/form-core

npm i https://pkg.pr.new/@tanstack/form-core@1404

@tanstack/lit-form

npm i https://pkg.pr.new/@tanstack/lit-form@1404

@tanstack/react-form

npm i https://pkg.pr.new/@tanstack/react-form@1404

@tanstack/svelte-form

npm i https://pkg.pr.new/@tanstack/svelte-form@1404

@tanstack/solid-form

npm i https://pkg.pr.new/@tanstack/solid-form@1404

@tanstack/vue-form

npm i https://pkg.pr.new/@tanstack/vue-form@1404

commit: 0c5b406

[LeCarbonator]

The library already adds multiple helper functions for arrays (pushValue(), insertValue(), swapValues()) because the meta has to be carefully accounted for during the update.

Following this principle, I suggest there should be one (or optionally two) helper methods added in this PR:

clearValues()

Clear the values from the array.

This technically can be done as edge case check in setFieldValue(), but I think this follows the established array methods better.

filterValues(callback)

Filter the values in the array based on this condition

The helper function would keep track of which indeces were removed and update the meta accordingly.

[LeCarbonator]

The provided test case will always fail because the items field starts with the string items. This is an easy fix though, so not that big of a deal.

[Pascalmh]

I'll rewrite the tests to use clearValues instead and change to assertions to be more explicit

[LeCarbonator]

Sounds good. I got an implementation of clearValues ready for testing as well

[LeCarbonator]

Since we're adding two new methods, the title should be changed to feat(form-core) so that the bot creates the proper semantic versioning

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.95%. Comparing base (ba66490) to head (0c5b406).
Report is 18 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1404      +/-   ##
==========================================
+ Coverage   88.52%   88.95%   +0.42%     
==========================================
  Files          28       31       +3     
  Lines        1316     1394      +78     
  Branches      343      351       +8     
==========================================
+ Hits         1165     1240      +75     
- Misses        134      137       +3     
  Partials       17       17              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[LeCarbonator]

How should onChange validation work in filterValues?

Currently:

• swapValues calls it on array, array[fromIndex] and array[toIndex]
• removeValue calls it on the array and all fields starting from index
• insertValue calls it on the array and all fields starting from index

With this information, I deduced that

• clearValues only needs to call it on the array itself

Should filterValues do:

• array + validation starting from the first index that has a shifted meta
• array + validation on all fields
• array
  ?