Documentation clarification value vs defaultValue

[st0w]

I have been working with react-select and have been using a creatable multi. The flexibility is great, however there is a lack of clarity in the documentation that led to a lot of lost time trying to troubleshoot.

My goal was to use creatable multi with grouping that allowed users to tag items on a page, and allow users to select or create new groupings at the time of new tag creation. I had the modal working, new groups were being created, new tags were being created in the back-end DB, but they weren't being reflected in the frontend until page refresh. If I set a poll interval in useQuery to force updates and tied that to the state variables, the multi selects would update to show the new tag - but the item the new tag was created with would show the new tag in the list of possible options, not as selected. On page refresh, everything looked as it should.

The ultimate issue I had was that I used CreatableSelect using defaultValue tied to the state variable, but I should have been using value.

The crux of the problem is that defaultValue is shown in examples being set to a state variable, but nowhere in the docs is there mention that subsequent changes to that state value are NOT reflected or updated in the UI. I spent hours and hours troubleshooting and ensuring that all state variables were being updated, and even ensuring the parent options state array was updated before the selectedOptions was updated, in case it would fail to add a new item if that item didn't exist in the parent options array.

The examples for multi show 'defaultValue' and don't reference value. No explanation is given that this seeds an initial value, but will not update on changes to a linked state variable.

The "Creatable Multiselect Example" on the Creatable page and the linked source code don't use value or defaultValue, and give no explanation.

The "Advanced Example" on the Creatable page uses value, but does not give an explanation of why that instead of defaultValue.

The full props API documentation page just lists defaultValue three times with the possible values that can be given to it. No information about it is mentioned - specifically that even if a state variable is passed, subsequent changes to that value will not be reflected. In retrospect, the only minor reference is that it says ReadonlyArray as one of those possible values.

The only reason I figured it out was a similar post from someone in November 2021 who also was using defautlValue when they should have been using value. A one sentence clarification in the documentation in one or two places would go a very long way and likely save others from spending a lot of time trying to troubleshoot something that is simple to address.

[Rall3n]

Hello @st0w,

the difference value <-> defaultValue is the same as with basic React HTML form elements (see React documentation: Uncontrolled components). One always sets the value when updated (controlled), the other only on first render (uncontrolled).

Improving the documentation is a big item on our todo, but you are welcome to open a PR with suggestions if you'd like to.

[st0w]

Thanks for the response! I was going to suggest that very same link to the React docs, which I found in the course of troubleshooting this. :) Something like that would be a great addition to the docs. And glad to hear the documentation is on the todo! And to be clear, I'm a big fan of the control. I'm using it in a lot of places, and loves the power and control it provides.

Thanks again!