How to Preserve Array Field Key Stability When Changing Form Data in a Controlled Form?

[mike-capyh]

Prerequisites

• I have read the documentation

What theme are you using?

mui

What is your question?

I'm attempting to add UI/components that modify form state directly.

Making the whole form 'controlled' (in the React sense) by a wrapping component, ie by tying RJSF Form formData and onChange to React.useState, seems to mostly work. The form data can be modified in the wrapper component via the state setter and responds mostly how I'd like. However, I've run into problems with array field key stability. I'll get into details of that below, but it might be an XY problem if there's a better way to take control of form data:

• Is this kind of 'controlled' RJSF form an intended/supported use case?
  • (The docs seem to imply that the formData prop to Form is only to set default/initial data; perhaps using it this way is a stretch?)
  • (edit: yes, controlled rjsf forms are supported, per comment below from heath-freenome)
• Are there any preferred alternatives?
  • (I've considered using an ArrayField custom field and going through its onChange; but this still runs into the key stability issue; going through the array items themselves wouldn't allow eg an append)

The array key stability problem:

Assuming the controlled form setup above, when the form data is updated by calling the state setter (from React.useState), it clobbers the stable keys that the ArrayField sets up internally, ie the ones implemented in #1335 to fix #1046 . As a result they get reset on re-render, and open the door to symptoms that #1335 hoped to prevent (edit: actually, this probably (?) only causes extra re-renders; at the moment there are no known issues caused by this - if anyone discovers an issue caused by this please link this issue or comment/re-open).

As a concrete example of what can break: a custom ArrayFieldTemplate with item add/remove animations via react-transition-group might key the transitions off the array item key; when the keys get clobbered, the next array item add animates as if all items (including existing ones) are being newly added. (edit: this was a red herring, and likely actually an integration issue between react 19 and react-transition-group)

A work-around?

A (very fragile) work-around is to pass a key remapper function down through eg formContext and having a custom ArrayField field/template call it on re-render, and use the remapped keys as the actual array item keys:

interface FormContext {
  arrayKeyMapper?: (arrayId: string, index: number, key: string) => string
}

That function then has to do a bit of a dance to map "new" internal keys to the old/stable ones, coordinated to any "clobbering" form data change. It might use the indices to do this, but has to be very careful to use those indices 'safely' relative to the actual form data change operation. This... works... but it is a lot of complexity and fragility.

Is there a cleaner way to accomplish this?

Thank you very much for the library, and for your help!

[heath-freenome]

@mike-capyh It seems like you have found a bug where arrays get messed up in a controlled state? Per your question Is this kind of 'controlled' RJSF form an intended/supported use case?, the answer is yes it is intended to support controlled states. That said, I'm guessing the bug you found may be located in the getDerivedStateFromProps() function. Are you willing to debug/fix the problem for us?

[mike-capyh]

I'll do what I can to provide information, but I'm hesitant to attempt a concrete fix. The main reason is that, so far, I haven't been able to figure out a general fix for this that doesn't involve rjsf interface changes. (and even allowing api changes, I haven't figured out any truly clean fixes).

Hopefully someone a bit wiser with respect to the RJSF api can come up with a better battle plan. If I see such a plan, I could probably find time to help with the plumbing.

The crux of the problem is that currently, the stable id mapping is in a weird "in-between" space: it is, and isn't, form state. It is form state in the sense that without maintaining the mapping, key stability breaks down. It isn't form state in the sense that it is not part of formData (intentionally), and not exposed externally. Since it is not exposed externally, there is no way to make a sane formData deep copy that includes/preserves the mapping. We need such a deep copy if we're doing a traditional React controlled input ie setState call (my understanding is that in rjsf, this would be a deep copy of form data and then a call to a wrapped/intercepted rjsf onChange).

A secondary, yet conceptually central, issue is that this kind of controlled form usage tells the rjsf form nothing about what array operation happened. All the internal helpers passed around by the templates are logical array operations (append/insert/swap/remove/etc) that can wrap the formData manipulations with corresponding/consistent changes to the array key mappings. However, React setState-style usage results in a totally new object with no easy way to know how the before/after state relates, and thus how the array item keys can be consistently remapped. Put another way, if all ways to change array state advertised what kind of change was happening, then the array keys could always be remapped internally, regardless of the above-mentioned deep copy problem (mapping being external to formData).

Some likely-viable fixes that do involve api changes (these are just my brain-storming, and I'm not terribly fond of any of these):

• (easiest?) expose a supported way to specify how array ids are done (possibly a uiSchema option?). If this option allows consumers to specify an array item field to use as the key directly, and/or a function to map a form field, it would at least allow consumers to work around the issue without getting too hacky. I'm not too sure how to do this in a general way such that the DX/ergonomics feel good though. Something like this might be 'nice to have', since some rjsf consumers may already have "better" candidate keys (eg if the array items are already db-persisted and have primary keys sitting around, then being able to use those primary keys would be ideal). However, a key downside is this still leaves the default auto-mapping behavior subtly broken, and with no clear contender for a "new default".
• expose both a way to query the array keys, and a way to tell the array template when/how they shifted. eg, if I'm about to trigger an append, I query and get ids [A, B], I can do the append and then say updateArrayKeys([A, B, null]) to tell the form to keep using the old ids, and to generate a new one for the appended element. Not the greatest ergonomics/DX for the consumer though.
• expose some other set of helper functions to enable deep-copying of the formData in preparation for a call to onChange (or possibly a new, 'sanctioned' setFormData helper for controlled form purposes), such that supplementary data not usually included in formData is also effectively copied (in this case, the array id mappings). I haven't attempted to sketch out what such an api would look like, but my feeling is that it might get ugly fast: since the array mappings are intentionally kept out of formData, but the copy would have to be aware of them, this would likely require multiple public functions to be aware of such "supplemental" data, and a bunch of old api usages would have to be deprecated or documented as broken. Hopefully I'm just missing some way to make this approach clean, but at the moment it feels very complex and a bit of a lift.

For what it is worth, we actually do have a fix that doesn't require api changes... well, sort of. Unfortunately, it isn't general, nor particularly ergonomic. It focuses on the second conceptual problem I outlined above: not knowing which array operation occurred. Whenever the external caller modifies controlled formData, at that point in time, they know which operation is happening.

So the hack is:

• create both custom ArrayField and ArrayFieldTemplate
• ArrayFieldTemplate knows the id mappings and can pass them on to the ArrayField
• ArrayField can intercept onChange, wrap it in helpers for specific array operations, eg append, and then pass those helpers up to the consumer via (an imperative-style) ref.
• those wrappers can use the id mapping information from the template to be aware of both old/new internal keys, and 'remap' on such operations as appropriate; they pass a new key back down to the template to use as the actual item key (the internal rjsf ones are only used at this intercept layer).

So the "no api changes" is a bit of a lie, in that the consumer has to use the imperative api exposed by the ref to avoid issues, and the general controlled rjsf onChange is still broken.

Apologies for the rambling info dump; please do let me know if I can help clarify any of the above. Hopefully someone smarter than me can come up with a less-ugly battle plan!

[mike-capyh]

On further investigation, this issue is mostly asymptomatic / red-herring for our particular use case (details below). The ids are getting clobbered, but ... given the subtlety/complexity of this, it probably isn't worth devoting time and effort to a fix unless a concrete symptom is found. Apologies for the noise, and thank you for your time!

We retested our transitions issue after implementing the above-described custom field/template hack and confirming that ids were now behaving as expected. Unfortunately, it did not resolve, and we went back to digging. For the curious, an actual resolution was to pin react to pre-v19; there seems to be a fishy interaction between react 19 and the comparatively ancient react-transition-group library.

In hindsight, it probably makes sense that the array keys getting clobbered and reset to new guids wouldn't cause too many obvious issues. If they got set to ids that had already been in use, all sorts of chaos could result, but being reset to a new unused id probably mostly just causes extra re-renders (at least in a React component that is correct, in the re-render idempotent sense).

[heath-freenome]

@mike-capyh Hi Mike. Thanks for all the explanations and eventual discovery. And wow, React 19... Yeah I can imagine that such a big upgrade could cause new issues to crop up. Not having switched over yet, I don't have the experience of how it will affect all the code. Did you want to keep the issue open?

[mike-capyh]

@heath-freenome Unless new information comes up, we won't be pursuing this issue further on our end, so please feel free to close/modify the issue however best helps the project/maintainers. I edited the main points from the thread into the initial post in case anyone else runs into this.

[mike-capyh]

Oh, and fwiw, we didn't notice any other obvious issues when we tested react 19, so at least for our usage, rjsf appears to be react19-ready. We're trying to avoid doing anything too exotic, so take with a grain of salt, but it's a data point.

[heath-freenome]

Closing issue per the author