Add new .form-control-with-iconsform-controls-with-icons

3 files changed, 229 insertions, 0 deletions

diff --git a/site/content/docs/5.0/forms/file.md b/site/content/docs/5.0/forms/file.md
index 466e7b095..7d04aeea2 100644
--- a/site/content/docs/5.0/forms/file.md
+++ b/site/content/docs/5.0/forms/file.md
@@ -71,3 +71,88 @@ You may also choose from small and large file inputs to match our similarly size
   </label>
 </div>
 {{< /example >}}
+
+## With icons
+
+Like our textual `.form-control`, you can overlay icons on `.form-file`s. See the [form control with icon docs]({{< docsref "/forms/form-control#with-icons" >}}) for more details.
+
+We've also customized the file input's text here to match our icon.
+
+{{< example >}}
+<div class="form-control-with-icon">
+  <div class="form-file">
+    <input type="file" class="form-file-input" id="formFileWithIcon">
+    <label class="form-file-label" for="formFileWithIcon">
+      <span class="form-file-text">Choose images...</span>
+      <span class="form-file-button">Browse</span>
+    </label>
+  </div>
+  <div class="form-control-icon">
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M12.002 4h-10a1 1 0 0 0-1 1v8l2.646-2.354a.5.5 0 0 1 .63-.062l2.66 1.773 3.71-3.71a.5.5 0 0 1 .577-.094l1.777 1.947V5a1 1 0 0 0-1-1zm-10-1a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2h-10zm4 4.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0z"/>
+      <path fill-rule="evenodd" d="M4 2h10a1 1 0 0 1 1 1v8a1 1 0 0 1-1 1v1a2 2 0 0 0 2-2V3a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2h1a1 1 0 0 1 1-1z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
+
+### Spinners
+
+You can also place any of Bootstrap's [spinners]({{< docsref "/components/spinners" >}}) within the `.form-control-icon`.
+
+{{< example >}}
+<div class="form-control-with-icon">
+  <div class="form-file">
+    <input type="file" class="form-file-input" id="formFileWithSpinner">
+    <label class="form-file-label" for="formFileWithSpinner">
+      <span class="form-file-text">Choose images...</span>
+      <span class="form-file-button">Browse</span>
+    </label>
+  </div>
+  <div class="form-control-icon">
+    <div class="spinner-border spinner-border-sm" role="status">
+      <span class="visually-hidden">Loading...</span>
+    </div>
+  </div>
+</div>
+{{< /example >}}
+
+### Sizing
+
+Add `.form-file-sm` or `.form-file-lg` to your `.form-file` and the `.form-control-icon` will automatically resize. However, the sizing of the icons themselves is up to you.
+
+{{< example >}}
+<div class="form-control-with-icon">
+  <div class="form-file form-file-sm">
+    <input type="file" class="form-file-input" id="formFileWithIconSm">
+    <label class="form-file-label" for="formFileWithIconSm">
+      <span class="form-file-text">Choose images...</span>
+      <span class="form-file-button">Browse</span>
+    </label>
+  </div>
+  <div class="form-control-icon">
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M12.002 4h-10a1 1 0 0 0-1 1v8l2.646-2.354a.5.5 0 0 1 .63-.062l2.66 1.773 3.71-3.71a.5.5 0 0 1 .577-.094l1.777 1.947V5a1 1 0 0 0-1-1zm-10-1a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2h-10zm4 4.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0z"/>
+      <path fill-rule="evenodd" d="M4 2h10a1 1 0 0 1 1 1v8a1 1 0 0 1-1 1v1a2 2 0 0 0 2-2V3a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2h1a1 1 0 0 1 1-1z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
+
+{{< example >}}
+<div class="form-control-with-icon">
+  <div class="form-file form-file-lg">
+    <input type="file" class="form-file-input" id="formFileWithIconLg">
+    <label class="form-file-label" for="formFileWithIconLg">
+      <span class="form-file-text">Choose images...</span>
+      <span class="form-file-button">Browse</span>
+    </label>
+  </div>
+  <div class="form-control-icon">
+    <svg width="1.5em" height="1.5em" viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M12.002 4h-10a1 1 0 0 0-1 1v8l2.646-2.354a.5.5 0 0 1 .63-.062l2.66 1.773 3.71-3.71a.5.5 0 0 1 .577-.094l1.777 1.947V5a1 1 0 0 0-1-1zm-10-1a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2h-10zm4 4.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0z"/>
+      <path fill-rule="evenodd" d="M4 2h10a1 1 0 0 1 1 1v8a1 1 0 0 1-1 1v1a2 2 0 0 0 2-2V3a2 2 0 0 0-2-2H4a2 2 0 0 0-2 2h1a1 1 0 0 1 1-1z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
diff --git a/site/content/docs/5.0/forms/form-control.md b/site/content/docs/5.0/forms/form-control.md
index 3f10138e9..98375e301 100644
--- a/site/content/docs/5.0/forms/form-control.md
+++ b/site/content/docs/5.0/forms/form-control.md
@@ -96,3 +96,67 @@ Learn more about [support for datalist elements](https://caniuse.com/#feat=datal
   <option value="Chicago">
 </datalist>
 {{< /example >}}
+
+## With icons
+
+Wrap your form control in an element with `.form-control-with-icon`, then add a new element as a sibling to the form control with `.form-control-icon`. Place your icons within that new element. Icons will be automatically centered vertically and horizontally, but the sizing of them is up to you.
+
+You can also add icons [to selects]({{< docsref "/forms/select#with-icons" >}}) and to [file inputs]({{< docsref "/forms/file#with-icons" >}}). Textareas are currently not supported.
+
+Examples below are shown with [Bootstrap Icons](https://icons.getbootstrap.com).
+
+{{< example >}}
+<label for="formControlWithIcon" class="form-label">Email address</label>
+<div class="form-control-with-icon">
+  <input type="email" class="form-control" id="formControlWithIcon" placeholder="[email protected]">
+  <div class="form-control-icon">
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M0 4a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V4zm2-1a1 1 0 0 0-1 1v.217l7 4.2 7-4.2V4a1 1 0 0 0-1-1H2zm13 2.383l-4.758 2.855L15 11.114v-5.73zm-.034 6.878L9.271 8.82 8 9.583 6.728 8.82l-5.694 3.44A1 1 0 0 0 2 13h12a1 1 0 0 0 .966-.739zM1 11.114l4.758-2.876L1 5.383v5.73z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
+
+### Spinners
+
+You can also place any of Bootstrap's [spinners]({{< docsref "/components/spinners" >}}) within the `.form-control-icon`.
+
+{{< example >}}
+<label for="formControlWithSpinner" class="form-label">Email address</label>
+<div class="form-control-with-icon">
+  <input type="email" class="form-control" id="formControlWithSpinner" placeholder="[email protected]">
+  <div class="form-control-icon">
+    <div class="spinner-border spinner-border-sm" role="status">
+      <span class="visually-hidden">Loading...</span>
+    </div>
+  </div>
+</div>
+{{< /example >}}
+
+### Sizing
+
+Add `.form-control-sm` or `.form-control-lg` to your `.form-control` and the `.form-control-icon` will automatically resize. However, the sizing of the icons themselves is up to you.
+
+{{< example >}}
+<label for="formControlWithIconSm" class="form-label">Email address</label>
+<div class="form-control-with-icon">
+  <input type="email" class="form-control form-control-sm" id="formControlWithIconSm" placeholder="[email protected]">
+  <div class="form-control-icon">
+    <svg width="1em" height="1em" viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M0 4a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V4zm2-1a1 1 0 0 0-1 1v.217l7 4.2 7-4.2V4a1 1 0 0 0-1-1H2zm13 2.383l-4.758 2.855L15 11.114v-5.73zm-.034 6.878L9.271 8.82 8 9.583 6.728 8.82l-5.694 3.44A1 1 0 0 0 2 13h12a1 1 0 0 0 .966-.739zM1 11.114l4.758-2.876L1 5.383v5.73z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
+
+{{< example >}}
+<label for="formControlWithIconLg" class="form-label">Email address</label>
+<div class="form-control-with-icon">
+  <input type="email" class="form-control form-control-lg" id="formControlWithIconLg" placeholder="[email protected]">
+  <div class="form-control-icon">
+    <svg width="1.5em" height="1.5em" viewBox="0 0 16 16" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M0 4a2 2 0 0 1 2-2h12a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V4zm2-1a1 1 0 0 0-1 1v.217l7 4.2 7-4.2V4a1 1 0 0 0-1-1H2zm13 2.383l-4.758 2.855L15 11.114v-5.73zm-.034 6.878L9.271 8.82 8 9.583 6.728 8.82l-5.694 3.44A1 1 0 0 0 2 13h12a1 1 0 0 0 .966-.739zM1 11.114l4.758-2.876L1 5.383v5.73z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
diff --git a/site/content/docs/5.0/forms/select.md b/site/content/docs/5.0/forms/select.md
index e8c62e8f3..9ed6a6050 100644
--- a/site/content/docs/5.0/forms/select.md
+++ b/site/content/docs/5.0/forms/select.md
@@ -60,3 +60,83 @@ As is the `size` attribute:
   <option value="3">Three</option>
 </select>
 {{< /example >}}
+
+## With icons
+
+Like our textual `.form-control`, you can overlay icons on `.form-select`s. See the [form control with icon docs]({{< docsref "/forms/form-control#with-icons" >}}) for more details.
+
+{{< example >}}
+<label for="formSelectWithIcon" class="form-label">Choose one</label>
+<div class="form-control-with-icon">
+  <select class="form-select" aria-label="Default select example" id="formSelectWithIcon">
+    <option selected>Open this select menu</option>
+    <option value="1">One</option>
+    <option value="2">Two</option>
+    <option value="3">Three</option>
+  </select>
+  <div class="form-control-icon">
+    <svg width="1em" height="1em" viewBox="0 0 16 16"  fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M2.5 11.5A.5.5 0 0 1 3 11h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4A.5.5 0 0 1 3 7h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4A.5.5 0 0 1 3 3h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
+
+### Spinners
+
+You can also place any of Bootstrap's [spinners]({{< docsref "/components/spinners" >}}) within the `.form-control-icon`.
+
+{{< example >}}
+<label for="formSelectWithSpinner" class="form-label">Choose one</label>
+<div class="form-control-with-icon">
+  <select class="form-select" aria-label="Default select example" id="formSelectWithSpinner">
+    <option selected>Open this select menu</option>
+    <option value="1">One</option>
+    <option value="2">Two</option>
+    <option value="3">Three</option>
+  </select>
+  <div class="form-control-icon">
+    <div class="spinner-border spinner-border-sm" role="status">
+      <span class="visually-hidden">Loading...</span>
+    </div>
+  </div>
+</div>
+{{< /example >}}
+
+### Sizing
+
+Add `.form-select-sm` or `.form-select-lg` to your `.form-select` and the `.form-control-icon` will automatically resize. However, the sizing of the icons themselves is up to you.
+
+{{< example >}}
+<label for="formSelectWithIconSm" class="form-label">Choose one</label>
+<div class="form-control-with-icon">
+  <select class="form-select form-select-sm" aria-label="Default select example" id="formSelectWithIconSm">
+    <option selected>Open this select menu</option>
+    <option value="1">One</option>
+    <option value="2">Two</option>
+    <option value="3">Three</option>
+  </select>
+  <div class="form-control-icon">
+    <svg width="1em" height="1em" viewBox="0 0 16 16"  fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M2.5 11.5A.5.5 0 0 1 3 11h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4A.5.5 0 0 1 3 7h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4A.5.5 0 0 1 3 3h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}
+
+{{< example >}}
+<label for="formSelectWithIconLg" class="form-label">Choose one</label>
+<div class="form-control-with-icon">
+  <select class="form-select form-select-lg" aria-label="Large select example" id="formSelectWithIconLg">
+    <option selected>Open this select menu</option>
+    <option value="1">One</option>
+    <option value="2">Two</option>
+    <option value="3">Three</option>
+  </select>
+  <div class="form-control-icon">
+    <svg width="1.5em" height="1.5em" viewBox="0 0 16 16"  fill="currentColor" xmlns="http://www.w3.org/2000/svg">
+      <path fill-rule="evenodd" d="M2.5 11.5A.5.5 0 0 1 3 11h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4A.5.5 0 0 1 3 7h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5zm0-4A.5.5 0 0 1 3 3h10a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5z"/>
+    </svg>
+  </div>
+</div>
+{{< /example >}}