Merge pull request #4340 from JedWatson/#3006-Documentation-Additions…

…-and-Revisions

#3006: Documentation clarifications and Defining Components section

docs/examples/CustomSelectProps.js

@@ -0,0 +1,50 @@
+import React, { useState } from 'react';
+import Select, { components } from 'react-select';
+import { colourOptions } from '../data';
+
+const EMOJIS = ['👍', '🤙', '👏', '👌', '🙌', '✌️', '🖖', '👐'];
+
+const Control = ({ children, ...props }) => {
+  const { emoji, onEmojiClick } = props.selectProps;
+  const style = { cursor: 'pointer' };
+
+  return (
+    <components.Control {...props}>
+      <span onMouseDown={onEmojiClick} style={style}>
+        {emoji}
+      </span>
+      {children}
+    </components.Control>
+  );
+};
+
+const CustomSelectProps = props => {
+  const [clickCount, setClickCount] = useState(0);
+
+  const onClick = e => {
+    setClickCount(clickCount + 1);
+    e.preventDefault();
+    e.stopPropagation();
+  };
+
+  const styles = {
+    control: css => ({ ...css, paddingLeft: '1rem' }),
+  };
+
+  const emoji = EMOJIS[clickCount % EMOJIS.length];
+
+  return (
+    <Select
+      {...props}
+      emoji={emoji}
+      onEmojiClick={onClick}
+      components={{ Control }}
+      isSearchable
+      name="emoji"
+      options={colourOptions}
+      styles={styles}
+    />
+  );
+};
+
+export default CustomSelectProps;

docs/examples/index.js

@@ -13,6 +13,7 @@ export { default as CreatableInputOnly } from './CreatableInputOnly';
 export { default as CreateFilter } from './CreateFilter';
 export { default as CreatableMulti } from './CreatableMulti';
 export { default as CreatableSingle } from './CreatableSingle';
+export { default as CustomSelectProps } from './CustomSelectProps';
 export { default as CustomClearIndicator } from './CustomClearIndicator';
 export { default as CustomDropdownIndicator } from './CustomDropdownIndicator';
 export { default as CustomLoadingIndicator } from './CustomLoadingIndicator';

docs/pages/advanced/index.js

@@ -53,6 +53,15 @@ export default function Advanced() {
       React-Select exports a createFilter function that returns a filterOption method. By using this, users can pick and choose bits of the filtration logic to customise,
       without having to rewrite the logic wholesale.
 
+      ~~~jsx
+      // default filter configuration 
+      ignoreCase: true,
+      ignoreAccents: true,
+      matchFrom: 'any',
+      stringify: option => \`\${option.label} \${option.value}\`,
+      trim: true,
+      ~~~
+
       Below is an example of how you could use the createFilter function to customise filtration logic in react-select.
 
       ${(
@@ -78,6 +87,15 @@ export default function Advanced() {
           <CustomFilterOptions />
         </ExampleWrapper>
       )}
+      ~~~jsx 
+      ~~~
+      > Please note that if you are using a Select that is creatable, you would also likey want to include the "Create" option.
+      ~~~jsx
+      const filterOption = (candidate, input) => {
+        return candidate.data.__isNew__ || candidate.label.includes(input);
+      };
+      ~~~
+
 
       ## Replacing builtins
       For a list of builtins that we expose, please see the API docs [here](/props#prop-types).
@@ -161,7 +179,7 @@ export default function Advanced() {
       By explicitly passing you what type of change event has been fired, we allow you to have more granular control
       over how the select behaves after an onChange even is fired.
 
-      Below is an example of replicating the behaviour supported by the (deprecated) onSelectResetsInput and (deprecated) closeMenuOnSelect props in react-select v1
+      Below is an example of replicating the behaviour of the deprecated props from react-select v1, onSelectResetsInput and closeOnSelect
 
       ${(
         <ExampleWrapper

docs/pages/components/index.js

@@ -4,6 +4,7 @@ import { Helmet } from 'react-helmet';
 import md from '../../markdown/renderer';
 import ExampleWrapper from '../../ExampleWrapper';
 import {
+  CustomSelectProps,
   CustomClearIndicator,
   CustomDropdownIndicator,
   CustomLoadingIndicator,
@@ -125,6 +126,60 @@ export default function Components() {
 
         ~~~
 
+        ## Defining components
+        
+        When defining replacement components, it is important to do so __outside__ the scope of 
+        rendering the Select. Defining a replacement component directly in the components prop can 
+        cause issues. 
+        
+        On this topic, React 
+        [documentation](https://reactjs.org/docs/higher-order-components.html#dont-use-hocs-inside-the-render-method)
+        has the following to say:
+
+        > The problem here isn’t just about performance — remounting a component causes the state
+        of that component and all of its children to be lost.
+        
+        This statement applies as well when replacing components in react-select with inline definitions. 
+
+        ~~~jsx
+        // Bad: Inline declaration will cause remounting issues
+        const BadSelect = props => (
+          <Select {...props} components={{
+            Control: ({ children, ...rest }) => (
+              <components.Control {...rest}>
+                👎 {children}
+              </components.Control>
+            )}} 
+          />
+        )
+
+        // Good: Custom component declared outside of the Select scope
+        const Control = props => ({ children, ...rest }) => (
+          <components.Control {...rest}>
+            👍 {children}
+          </components.Control>
+        );
+
+        const GoodSelect = props => <Select {...props} components={{ Control }} />
+
+        ~~~
+
+        There will likely be times that data or methods may need to be shared,
+        but this can be achieved with the \`selectProps\` prop passed to each component.
+
+        ${(
+          <ExampleWrapper
+            label="Custom Component with selectProps Example"
+            urlPath="docs/examples/CustomSelectProps.js"
+            raw={require('!!raw-loader!../../examples/CustomSelectProps.js')}
+          >
+            <CustomSelectProps />
+          </ExampleWrapper>
+        )}
+
+        ~~~
+        ~~~
+
         ## Adjusting the Styling
 
         The \`styles\` prop allows you to pass styles to a particular component, without

packages/react-select/src/Select.js

@@ -81,7 +81,7 @@ export type Props = {
   'aria-labelledby'?: string,
   /* Focus the control when it is mounted */
   autoFocus?: boolean,
-  /* Remove the currently focused option when the user presses backspace */
+  /* Remove the currently focused option when the user presses backspace when Select isClearable or isMulti */
   backspaceRemovesValue: boolean,
   /* Remove focus from the input when the user selects an option (handy for dismissing the keyboard on touch devices) */
   blurInputOnSelect: boolean,