1 files changed, 85 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 >}}