From c72c949cf47dffd686f79d06f10557a5110142b5 Mon Sep 17 00:00:00 2001
From: Nathan Hunzaker <nate.hunzaker@gmail.com>
Date: Mon, 19 Dec 2016 08:35:54 -0500
Subject: [PATCH] Update input example readme

---
 examples/inputs/README.md | 50 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/examples/inputs/README.md b/examples/inputs/README.md
index 5c4055dca3831..3bc2326667544 100644
--- a/examples/inputs/README.md
+++ b/examples/inputs/README.md
@@ -1,3 +1,49 @@
-# Input Test Case
+# Inputs
 
-More information around the history of inputs could go here.
+This fixture should help identify edge cases with inputs. There are a couple of
+important concepts to be aware of when working on inputs in React.
+
+## `defaultValue` vs `value`
+
+An input's value is drawn from two properties: `defaultValue` and `value`.
+
+The `defaultValue` property directly maps to the value _attribute_, for example:
+
+```javascript
+var input = document.createElement('input')
+input.defaultValue = 'hello'
+
+console.log(input.getAttribute('value')) // => "hello"
+```
+
+The `value` property manipulates the _working value_ for the input. This property
+changes whenever the user interacts with an input, or it is modified with JavaScript:
+
+```javascript
+var input = document.createElement('input')
+input.defaultValue = 'hello'
+input.value = 'goodbye'
+
+console.log(input.getAttribute('value')) // => "hello"
+console.log(input.value) // => "goodbye"
+```
+
+## value detachment
+
+Until `value` is manipulated by a user or JavaScript, manipulating `defaultValue`
+will also modify the `value` property:
+
+```javascript
+var input = document.createElement('input')
+// This will turn into 3
+input.defaultValue = 3
+// This will turn into 5
+input.defaultValue = 5
+// This will turn into 7
+input.value = 7
+// This will do nothing
+input.defaultValue = 1
+```
+
+**React detaches all inputs**. This prevents `value` from accidentally updating if
+`defaultValue` changes.