Merge pull request #18771 from twbs/v4-custom-forms-revamp

v4: Custom forms (disabled state, revamp, etc)

docs/components/forms.md

@@ -543,7 +543,7 @@ Block help text—for below inputs or for longer lines of help text—can be eas
 <label for="inputPassword5">Password</label>
 <input type="password" id="inputPassword5" class="form-control" aria-describedby="passwordHelpBlock">
 <p id="passwordHelpBlock" class="text-muted">
-  Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters or emoji. 
+  Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters or emoji.
 </p>
 {% endexample %}
 
@@ -607,33 +607,33 @@ Each checkbox and radio is wrapped in a `<label>` for three reasons:
 - It provides a helpful and semantic wrapper to help us replace the default `<input>`s.
 - It triggers the state of the `<input>` automatically, meaning no JavaScript is required.
 
-We hide the default `<input>` with `opacity` and use the `.c-indicator` to build a new custom form control. We can't build a custom one from just the `<input>` because CSS's `content` doesn't work on that element.
+We hide the default `<input>` with `opacity` and use the `.custom-control-indicator` to build a new custom form indicator in its place. Unfortunately we can't build a custom one from just the `<input>` because CSS's `content` doesn't work on that element.
 
-With the sibling selector (`~`), we use the `:checked` state to trigger a makeshift checked state on the custom control.
+We use the sibling selector (`~`) for all our `<input>` states—like `:checked`—to properly style our custom form indicator. When combined with the `.custom-control-description` class, we can also style the text for each item based on the `<input>`'s state.
 
 In the checked states, we use **base64 embedded SVG icons** from [Open Iconic](https://useiconic.com/open). This provides us the best control for styling and positioning across browsers and devices.
 
 #### Checkboxes
 
 {% example html %}
-<label class="c-input c-checkbox">
-  <input type="checkbox">
-  <span class="c-indicator"></span>
-  Check this custom checkbox
+<label class="custom-control custom-checkbox">
+  <input type="checkbox" class="custom-control-input">
+  <span class="custom-control-indicator"></span>
+  <span class="custom-control-description">Check this custom checkbox</span>
 </label>
 {% endexample %}
 
 Custom checkboxes can also utilize the `:indeterminate` pseudo class when manually set via JavaScript (there is no available HTML attribute for specifying it).
 
 <div class="bd-example bd-example-indeterminate">
-  <label class="c-input c-checkbox">
-    <input type="checkbox">
-    <span class="c-indicator"></span>
-    Check this custom checkbox
+  <label class="custom-control custom-checkbox">
+    <input type="checkbox" class="custom-control-input">
+    <span class="custom-control-indicator"></span>
+    <span class="custom-control-description">Check this custom checkbox</span>
   </label>
 </div>
 
- If you're using jQuery, something like this should suffice:
+If you're using jQuery, something like this should suffice:
 
 {% highlight js %}
 $('.your-checkbox').prop('indeterminate', true)
@@ -642,43 +642,62 @@ $('.your-checkbox').prop('indeterminate', true)
 #### Radios
 
 {% example html %}
-<label class="c-input c-radio">
-  <input id="radio1" name="radio" type="radio">
-  <span class="c-indicator"></span>
-  Toggle this custom radio
+<label class="custom-control custom-radio">
+  <input id="radio1" name="radio" type="radio" class="custom-control-input">
+  <span class="custom-control-indicator"></span>
+  <span class="custom-control-description">Toggle this custom radio</span>
 </label>
-<label class="c-input c-radio">
-  <input id="radio2" name="radio" type="radio">
-  <span class="c-indicator"></span>
-  Or toggle this other custom radio
+<label class="custom-control custom-radio">
+  <input id="radio2" name="radio" type="radio" class="custom-control-input">
+  <span class="custom-control-indicator"></span>
+  <span class="custom-control-description">Or toggle this other custom radio</span>
 </label>
 {% endexample %}
 
-#### Stacked
+#### Disabled
 
-Custom checkboxes and radios are inline to start. Add a parent with class `.c-inputs-stacked` to ensure each form control is on separate lines.
+Custom checkboxes and radios can also be disabled. Add the `disabled` boolean attribute to the `<input>` and the custom indicator and label description will be automatically styled.
 
 {% example html %}
-<div class="c-inputs-stacked">
-  <label class="c-input c-radio">
-    <input id="radioStacked1" name="radio-stacked" type="radio">
-    <span class="c-indicator"></span>
-    Toggle this custom radio
+<label class="custom-control custom-checkbox">
+  <input type="checkbox" class="custom-control-input" disabled>
+  <span class="custom-control-indicator"></span>
+  <span class="custom-control-description">Check this custom checkbox</span>
+</label>
+
+<label class="custom-control custom-radio">
+  <input id="radio3" name="radioDisabled" type="radio" class="custom-control-input" disabled>
+  <span class="custom-control-indicator"></span>
+  <span class="custom-control-description">Toggle this custom radio</span>
+</label>
+{% endexample %}
+
+
+#### Stacked
+
+Custom checkboxes and radios are inline to start. Add a parent with class `.custom-controls-stacked` to ensure each form control is on separate lines.
+
+{% example html %}
+<div class="custom-controls-stacked">
+  <label class="custom-control custom-radio">
+    <input id="radioStacked1" name="radio-stacked" type="radio" class="custom-control-input">
+    <span class="custom-control-indicator"></span>
+    <span class="custom-control-description">Toggle this custom radio</span>
   </label>
-  <label class="c-input c-radio">
-    <input id="radioStacked2" name="radio-stacked" type="radio">
-    <span class="c-indicator"></span>
-    Or toggle this other custom radio
+  <label class="custom-control custom-radio">
+    <input id="radioStacked2" name="radio-stacked" type="radio" class="custom-control-input">
+    <span class="custom-control-indicator"></span>
+    <span class="custom-control-description">Or toggle this other custom radio</span>
   </label>
 </div>
 {% endexample %}
 
 ### Select menu
 
-Custom `<select>` menus need only a custom class, `.c-select` to trigger the custom styles.
+Custom `<select>` menus need only a custom class, `.custom-select` to trigger the custom styles.
 
 {% example html %}
-<select class="c-select">
+<select class="custom-select">
   <option selected>Open this select menu</option>
   <option value="1">One</option>
   <option value="2">Two</option>
@@ -690,14 +709,16 @@ Custom selects degrade nicely in IE9, receiving only a handful of overrides to r
 
 ### File browser
 
+The file input is the most gnarly of the bunch and require additional JavaScript if you'd like to hook them up with functional *Choose file...* and selected file name text.
+
 {% example html %}
-<label class="file">
-  <input type="file" id="file">
-  <span class="file-custom"></span>
+<label class="custom-file">
+  <input type="file" id="file" class="custom-file-input">
+  <span class="custom-file-control"></span>
 </label>
 {% endexample %}
 
-The file input is the most gnarly of the bunch. Here's how it works:
+Here's how it works:
 
 - We wrap the `<input>` in a `<label>` so the custom control properly triggers the file browser.
 - We hide the default file `<input>` via `opacity`.
@@ -706,5 +727,3 @@ The file input is the most gnarly of the bunch. Here's how it works:
 - We declare a `height` on the `<input>` for proper spacing for surrounding content.
 
 In other words, it's an entirely custom element, all generated via CSS.
-
-**Heads up!** The custom file input is currently unable to update the *Choose file...* text with the filename. Without JavaScript, this might not be possible to change, but I'm open to ideas.