[TextField] Docs: "only single input." Checkbox: 3 checkboxes in a FormControl #22535

jonathan-stone · 2020-09-09T06:28:42Z

The documentation for FormControl explicitly states: Only one input can be used within a FormControl.
The demo of checkboxes on the Checkbox documentation page shows a FormControl containing three Checkbox components.

So, which one is correct?

The issue is present in the latest release.
I have searched the issues of this repository and believe that this is not a duplicate.

There are at least two related bugs that were closed:

This issue, Update Selection Controls Radio/Checkbox group demo, suggests that the demos for checkbox and radio button group be modified to not put multiple inputs inside a FormControl. Closed as not a bug, with comments that seem to indicate multiple text fields are a problem, but multiple checkboxes are okay.

[FormControl] Maximum update depth exceeded. Closed with comment You can only use a single input within a FormControl.

Current Behavior 😯

The example in the Checkbox documentation contradicts the documented API, by placing 3 checkboxes inside one FormControl

Expected Behavior 🤔

Possible fix 1:
The FormControl does not contain the text Only one input can be used within a FormControl. If there are cases where it's okay to use multiple inputs, and other cases where it doesn't work, the FormControl documents those. Seems like it may be okay to use multiple inputs but not multiple text inputs.

Or, option 2:
The Checkbox and Radio Button documentation sections do not show, in their demo code, examples of multiple inputs being used inside a FormControl.

Steps to Reproduce 🕹

Visit the docs page for FormControl. https://material-ui.com/api/form-control/ Note the text, with an adjacent yellow Warning icon, ⚠️Only one input can be used within a FormControl.
Visit the docs page for Checkbox, and scroll to the section "Checkboxes with FormGroup." https://material-ui.com/components/checkboxes/#checkboxes-with-formgroup
Click the <> button to show the source.
Scroll down in the source code to see the usage of FormControl. Note that inside each FormControl is a FormGroup containing three Checkbox inputs.

Context 🔦

I'm trying to figure out how FormControl fits in with Material-UI forms components. I'm confused by the conflicting docs.

Your Environment 🌎

n/a - docs

oliviertassinari · 2020-09-09T09:56:45Z

@jonathan-stone Thanks for raising this point of confusion. We had a first feedback for it in #16907 (comment).
I would propose we update the documentation to be more specific. It's multiple InputBase that isn't supported. It's basically what we mention in the warning

material-ui/packages/material-ui/src/FormControl/FormControl.js

Line 137 in 1332b92

'Material-UI: There are multiple InputBase components inside a FormControl.',

Regarding why this limitation? Consider this code:

import React from 'react';
import Input from '@material-ui/core/Input';
import FormControl from '@material-ui/core/FormControl';

export default () => {
  return (
    <FormControl>
      <Input value="a" />
      <Input />
    </FormControl>
  )
}

and how it looks like once focused:

We used to have an infinite loop (#12197), but I believe the issue was solved.

What about this diff?

diff --git a/packages/material-ui/src/FormControl/FormControl.js b/packages/material-ui/src/FormControl/FormControl.js
index 9b334c48b5..704475d7d3 100644
--- a/packages/material-ui/src/FormControl/FormControl.js
+++ b/packages/material-ui/src/FormControl/FormControl.js
@@ -57,7 +57,7 @@ export const styles = {
  * </FormControl>
  * ```
  *
- * ⚠️Only one input can be used within a FormControl.
+ * ⚠️ Only one `InputBase` can be used within a FormControl because it create visual inconsistencies.,
  */
 const FormControl = React.forwardRef(function FormControl(props, ref) {
   const {
@@ -134,9 +134,8 @@ const FormControl = React.forwardRef(function FormControl(props, ref) {
       if (registeredInput.current) {
         console.error(
           [
-            'Material-UI: There are multiple InputBase components inside a FormControl.',
-            'This is not supported. It might cause infinite rendering loops.',
-            'Only use one InputBase.',
+            'Material-UI: There are multiple `InputBase` components inside a FormControl.',
+            'This creates visual inconsistencies, only use one `InputBase`.',
           ].join('\n'),
         );
       }

Do you want to work on it?

jonathan-stone · 2020-09-10T06:01:27Z

Thanks for the quick reply, @oliviertassinari !
That change looks like a good one. It would be good to also specify which controls instantiate InputBase to help people who aren't familiar with it (like me!).

I'm just getting started with form components in MUI so I'd like to spend a few days learning before putting up any PRs, but I would be happy to help update the docs next week. Having read the context you provided above (thank you!), it seems like a good solution would be to update that sentence in the FormControl docs, to specify which inputs are allowed multiples inside a form control, and which aren't.

One thing I don't yet understand is what a FormControl component actually does and what difference it makes if you put multiple inputs into one, vs. not using a FormControl, vs. having multiple FormControls. Still going through the docs and examples to figure that out.

oliviertassinari · 2020-09-10T16:51:06Z

@jonathan-stone Right, InputBase is used by Input, OutlinedInput, and FilledInput. This information is not directly available. We could include it.

what a FormControl component actually does?

FormControl is meant to centralize the state between the different building blocks of the input.

would be happy to help update the docs next week.

Awesome :)

jonathan-stone added the status: needs triage label Sep 9, 2020

oliviertassinari changed the title ~~FormControl docs: "only single input." Checkbox docs: 3 checkboxes in a FormControl~~ [TextField] Docs: "only single input." Checkbox docs: 3 checkboxes in a FormControl Sep 9, 2020

oliviertassinari changed the title ~~[TextField] Docs: "only single input." Checkbox docs: 3 checkboxes in a FormControl~~ [TextField] Docs: "only single input." Checkbox: 3 checkboxes in a FormControl Sep 9, 2020

oliviertassinari added component: TextField docs good first issue and removed status: needs triage labels Sep 9, 2020

mbrookes assigned jonathan-stone Sep 10, 2020

mui-org / material-ui

[TextField] Docs: "only single input." Checkbox: 3 checkboxes in a FormControl #22535

[TextField] Docs: "only single input." Checkbox: 3 checkboxes in a FormControl #22535

jonathan-stone commented Sep 9, 2020 •

edited by mbrookes

oliviertassinari commented Sep 9, 2020

jonathan-stone commented Sep 10, 2020

oliviertassinari commented Sep 10, 2020 •

edited

mui-org / material-ui

Sponsor mui-org/material-ui

Join GitHub today

[TextField] Docs: "only single input." Checkbox: 3 checkboxes in a FormControl #22535

[TextField] Docs: "only single input." Checkbox: 3 checkboxes in a FormControl #22535

Comments

jonathan-stone commented Sep 9, 2020 • edited by mbrookes

Current Behavior 😯

Expected Behavior 🤔

Steps to Reproduce 🕹

Context 🔦

Your Environment 🌎

oliviertassinari commented Sep 9, 2020

jonathan-stone commented Sep 10, 2020

oliviertassinari commented Sep 10, 2020 • edited

jonathan-stone commented Sep 9, 2020 •

edited by mbrookes

oliviertassinari commented Sep 10, 2020 •

edited