JedWatson / JedWatson/react-select
formatGroupLabel returns string but not used that way in documentation
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 28k
- Forks
- 4.1k
- PR merge metrics
- No merged PRs in 30d
Description
Perhaps a breaking change for some so wanted to document it with a possibility to discuss/resolve this later.
Given these props, there are different expectations about the return type.
getOptionLabel => string
getOptionValue => string
formatOptionLabel => react.Node
formatGroupLabel => string
The nomenclature suggests that formatGroupLabel would likely be expected to render a react Node as well, but instead it is defined to return a string. I say likely expected because the first grouping example on the homepage of the documentation misuses this prop in this exact way.
const formatGroupLabel = data => (
<div style={groupStyles}>
<span>{data.label}</span>
<span style={groupBadgeStyles}>{data.options.length}</span>
</div>
);
export default () => (
<Select
defaultValue={colourOptions[1]}
options={groupedOptions}
formatGroupLabel={formatGroupLabel}
/>
);
While it might not be a big deal to some, misusing these props has an impact on accessibility as it is reliant to relay the label back to the screen reader and will instead return "object object" as the selected option.
Recommendations:
- Add
groupas a possible context forformatOptionLabelto consolidate the render functions there. - Remove/replace the code example shown above (and possibly other examples) in the documentation to convey best practices.
- Consider adding documentation about accessibility concerns when using
getOptionLabelandformatGroupLabel - Consider renaming
formatGroupLabeltogetGroupLabelin a future major release. - Consider adding console warnings when an object is stringified.
I could create a PR, but wanted to get thoughts on listed considerations before moving forward
Let it also be noted that the accessibility concerns around the current stringification has been noted here: https://github.com/JedWatson/react-select/issues/4134
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the grouping example on the documentation homepage and review the related accessibility discussion in issue 4134. Determine which of the listed recommendations are accepted, then update the affected documentation and examples so the agreed behavior and accessibility guidance are clear.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- accessibility, documentation, frontend
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100