diff --git a/docs/07-forms.md b/docs/07-forms.md index c452940d6..5f0c4ebdf 100644 --- a/docs/07-forms.md +++ b/docs/07-forms.md @@ -34,7 +34,7 @@ Like all DOM events, the `onChange` prop is supported on all native components a ## Controlled Components -An `` with `value` set is a *controlled* component. In a controlled ``, the value of the rendered element will always reflect the `value` prop. For example: +A **controlled** `` has a `value` prop. Rendering a controlled `` will reflect the value of the `value` prop. ```javascript render: function() { @@ -42,7 +42,7 @@ An `` with `value` set is a *controlled* component. In a controlled `; + return ( + + ); } ``` -In this example, we are simply accepting the newest value provided by the user and updating the `value` prop of the `` component. This pattern makes it easy to implement interfaces that respond to or validate user interactions. For example: +In this example, we are accepting the value provided by the user and updating the `value` prop of the `` component. This pattern makes it easy to implement interfaces that respond to or validate user interactions. For example: ```javascript handleChange: function(event) { @@ -65,7 +70,9 @@ In this example, we are simply accepting the newest value provided by the user a } ``` -This would accept user input but truncate the value to the first 140 characters. +This would accept user input and truncate the value to the first 140 characters. + +A **Controlled** component maintains its own internal state; the component renders purely based on props. ### Potential Issues With Checkboxes and Radio Buttons @@ -73,7 +80,7 @@ Be aware that, in an attempt to normalize change handling for checkbox and radio ## Uncontrolled Components -An `` that does not supply a `value` (or sets it to `null`) is an *uncontrolled* component. In an uncontrolled ``, the value of the rendered element will reflect the user's input. For example: +An `` without a `value` property is an *uncontrolled* component: ```javascript render: function() { @@ -83,6 +90,8 @@ An `` that does not supply a `value` (or sets it to `null`) is an *uncont This will render an input that starts off with an empty value. Any user input will be immediately reflected by the rendered element. If you wanted to listen to updates to the value, you could use the `onChange` event just like you can with controlled components. +An **uncontrolled** component maintains its own internal state. + ### Default Value If you want to initialize the component with a non-empty value, you can supply a `defaultValue` prop. For example: