React-select: Documentation very thorough but hard to get the "basics" from.

[benlieb]

I'm looking for a basic use case of react-select involving an onChange and setting a value but after 30 minutes reading the documentation I can't even tell what format to pass the value in as or what the prop should be.

Your documentation is detailed, but I'm afraid for me not very useable. I really don't know what I'm supposed to do with:

I appreciate your work, I really do, and this seems to be the best select component out there. But man, I feel so frustrated after so much time spent and still not being clear what to do.

[benlieb]

Thanks for your response. Unfortunately it is still not obvious to me from your response what the format of the value object must be.

Is it necessary that the object have both label and value? If this is the case then please state this in the documentation.

If this is the case I'm confused why you would say "An object. For example ...". {name: 'bob'} is also an object. Can that work?

I would have benefited from the clarity of somewhere in the documentation is stating that value objects must have these specific keys.

[cjke]

I came here searching for an identical issue. Unless https://react-select.com/home#getting-started has changed in the last month, the style of object passed to value isn't on the page you linked.

@benlieb has articulated his concern extremely well. There is no clear definition in the docs the "shape" the value object must take. Are both label and value needed? What happens if the object contains additional keys? And so on.

[cjke]

Query 1: I am looking for the definition/documentation for the "shape" of "Object" in the following (from https://react-select.com/props):

value

One of <
  Object,
  Array<Object>,
  null,
  undefined
>

Query 2: Does the "Object" shape need to be an exact match (do all keys need to exist and match) or a loose match (extra present keys are acceptable)?

[cjke]

The primary problem is my inability to find the exact shape needed for the "value" object in the documentation. It's identical to the issue raised in https://github.com/JedWatson/react-select/issues/4045#issuecomment-628953501 above.

For example, I would expect to see some shape definition like the below in the documentation (similar to "internal props" in https://react-select.com/props ):

type OptionObject = {
  name: string | number
  value: string | number
}
type Value = OptionObject | Array<OptionObject> | null | undefined

Along with a note such as "Additional keys in OptionObject will be ignored in the equality check".

Example
For example, if I'm passing the following as an options prop (and assume I am using the getOptionValue prop)

const types = [
  { id: 1, label: 'foo 1', meta: { bla: 77, foo: 1 } },
  { id: 2, label: 'foo 2', meta: { bla: 88, foo: 2 } },
  { id: 3, label: 'foo 3', meta: { bla: 99, foo: 3 } },
]

Now I need to set the value prop to pick the second option, should it be:

A:   { id: 2, label: 'foo 2', meta: { bla: 88, foo: 2 } }   // whole object ok?

or

B:  { id: 2, label: 'foo 2' }   // does it need to be the exact value/label pair?

or

C:  { id: 2 }   // or can I just get away with the value (id in this case) in an object?

Edit I appreciate you are trying to help but we may need some input from a contributor

[barrychapman]

@bladey / @manualva7 - Can someone elaborate on this issue please?

@benlieb was extremely clear in his issue. The documentation does NOT clearly state what the value object must be set to.

For example, if I am creating an Edit Form, and I need to 'preselect' the option in the Select, what do I need to set the state of that Select's value to?

Consider that we are using a record from a database table called actions - and action_id 253, corresponds to a label in the database as "Exec Action"

• Is it the key associated? (int 253)
• Is it a key/value pair? {action_id: 253}
• Is it a verbose label/value pair? {label: "Exec Action", value: 253}

If it is the verbose label/value pair, that just makes things like validation that much more complicated, as we then need to have some way to store the value that would be stored in the DB in the state object. We obviously are not going to store {label: "Exec Action", value: 253} in the database verbatim like that.

Shouldn't we be able to just use the value of the associated item in the list? We can assume that these will be unique by list, so why wouldn't we go this route?

I truly do not know why this needs to be so overly complex.

[barrychapman]

@manualva7

I guess the better question would be better suited to be - if _have_ to construct the value object in such a way, how do we extract the value only for insertion to the database? If I have this stored in my state as:

    this.state = {
          action_id: {
               value: <value here>
          }
    }

We would have to access it using this.state.action_id.value.value, which does not make a lot of sense

[benlieb]

It's disappointing that such a popular piece of open source software would have an advocate with this type of disposition. I didn't mean to stir up trouble with my original post. I honestly was just trying to figure out how to use the library. It seems others are having have a similar issue, but are expressing their trouble respectfully. This should be useful information for those trying to make the project better, not cause for anger and aggression. I don't understand.

And in case future edits shift what I'm referring to:

[Rall3n]

Is it necessary that the object have both label and value?

There is no clear definition in the docs the "shape" the value object must take. Are both label and value needed?

The objects can take any shape as long as you tell the Select component where to find a label and a value using the props getOptionLabel and getOptionValue.

{name: 'bob'} is also an object. Can that work?

As stated above, yes, using following example:

<Select value={{ name: 'bob' }} getOptionValue={option => option.name} getOptionLabel={option => option.name} />

I would have benefited from the clarity of somewhere in the documentation is stating that value objects must have these specific keys.

The documentation does NOT clearly state what the value object must be set to.

As you can tell the component exactly where to find a label and a value (see above), the docs are right in not saying that you need to have these specific keys. But I agree that they could have clarified on what that means exactly.

Does the "Object" shape need to be an exact match (do all keys need to exist and match) or a loose match (extra present keys are acceptable)?

No, the object only needs the keys you use to identify the value and the label using the getter-props mentioned above.

Shouldn't we be able to just use the value of the associated item in the list? We can assume that these will be unique by list, so why wouldn't we go this route?

Not in the current state, but I personally find it better this way. With having the value being an object, you are not dependent on the options list for its meta data (e.g. the label).

[bernard-leech]

It's disappointing that such a popular piece of open source software would have an advocate with this type of disposition.

@benlieb I agree that this is totally unacceptable language - nothing has happened in the last few days, so it looks like we're going to let it slide.

With a growing community, It's likely that toxic behaviour can surface again - might be a good opportunity to propose a code of conduct from one of the templates listed here:

https://github.com/JedWatson/react-select/community

[benlieb]

@bernard-leech Fair enough. We all do and say things sometimes that aren't awesome. I've done and said things I wish I hadn't my fare share of times and I'm a firm believer in second chances.

For my part, I can see that my original title for this issue could be read as a bit snarky. I originally had "Documentation can't see the forest for the trees". That was after 30 mins of not being able to find what I needed to implement the lib and I was feeling frustrated. I tried to express my appreciation for the work despite that, but yeah, it was a bit snarky. Though I don't think it warranted insult and aggression, I do intend to be more careful in the future.

Cheers all!

[cjke]

@benlieb - I'm not sure if manualva7 was referring to you, myself or barrychapman (he did use the plural form, so perhaps all three, who knows).

Personally I didn't take your original title or any of the other comments as being negative or snarky. Perhaps my "I appreciate you are trying to help but we may need some input from a contributor" comment got him offside.

It's unfortunate this conversation was sidetracked into some pretty rude commentary because the core question/issue was warranted.

As an aside, it looks like all his comments have been removed. Anyway, I second the need for a code of conduct

[barrychapman]

It's disappointing that such a popular piece of open source software would have an advocate with this type of disposition.

@benlieb I agree that this is totally unacceptable language - nothing has happened in the last few days, so it looks like we're going to let it slide.

With a growing community, It's likely that toxic behaviour can surface again - might be a good opportunity to propose a code of conduct from one of the templates listed here:

https://github.com/JedWatson/react-select/community

Yeah, because he BLOCKED us!

[barrychapman]

@cjke @bernard-leech

I also apologize if I came across strongly. I did not think my questions or comments were worded in a way that would illicit verbal violence, but I will also exercise caution from now on. It seems like we were honestly just trying to decipher the use-case we were both faced with.

And yes, I also felt the frustration. Thank you to @Rall3n for the clarification on how to define those parameters. That will help a lot going forward.

In the meantime, keep up the great work. The library is great, and does exactly what I need - so no complaints here!