Pattern: ISO-string date fields to avoid Date-object reactivity issues

[jiji-hoon96]

Has anyone else run into Date-object reactivity issues with TanStack Form's date fields? Closed issue #1712 ("isDefaultValue not updating when changing date field") surfaces a class of problem that comes from comparing Date instances by reference rather than value.

I work on Kalyx (a headless React DatePicker) and we took a different approach there — wanted to share the pattern in case it fits as a recipe or documentation note here.

The pattern

Use ISO 8601 UTC strings as the field value type, never Date objects:

const form = useForm({                                 
  defaultValues: {
    birthDate: '1990-01-01T00:00:00.000Z' as string | null,
  },                                                                                                                                                   
})
                                                                                                                                                       
<form.Field name="birthDate">                          
  {(field) => (
    <DatePicker
      value={field.state.value}
      onChange={field.handleChange}
    />
  )}                                                                                                                                                   
</form.Field>

Two things it gets you:

1. Reference equality works. defaultValue === currentValue is plain string comparison, so isDefaultValue / isPristine track correctly. The class of bug in isDefaultValue not updating when changing date field #1712 doesn't apply.
2. Validation and serialization are cheap. z.iso.datetime() validates without a Date round-trip, and you can serialize to JSON without manual.toISOString() calls.

Asking

• Would a documented recipe along these lines fit examples/react/? There's a simple example but no date-field one specifically, and date-related issues seem to converge on this same shape.
• Any reason TanStack Form would prefer recommending Date objects over ISO strings? Want to confirm direction before working on an example folder.

Happy to put together a self-contained examples/react/date-fields-iso/ example. Kalyx works as the picker because of the ISO contract, but the pattern is library-agnostic — anything that emits strings would do.

[MILLERMARRU]

To your second question directly: no, there's no framework-level reason TanStack Form would prefer Date objects, the library is generic over field value types, it doesn't special-case Date anywhere in its comparison or serialization logic. The reference-equality problem you're describing (and that #1712 hits) isn't TanStack Form defending some Date-aware behavior, it's just what you get from comparing two distinct Date instances with ===, which is true of isDefaultValue/dirty-tracking in basically any state library that does a shallow/reference check rather than a deep one.

So your ISO-string pattern isn't working around a documented preference, it's sidestepping a general JS footgun (reference vs. value equality on Date objects) that would show up the same way in any comparison that isn't Date-aware, TanStack Form included. Given that, it sounds like a genuinely useful addition to examples/react/, especially since you're right that it's library-agnostic on the picker side too, worth opening the PR you mentioned, that's the kind of "the framework doesn't fight you, here's the shape that avoids a common trap" content that's usually welcome as a recipe rather than requiring a design decision from the maintainers first.