diff options
Diffstat (limited to 'site/content/docs/5.2/forms')
| -rw-r--r-- | site/content/docs/5.2/forms/checks-radios.md | 307 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/floating-labels.md | 152 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/form-control.md | 152 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/input-group.md | 316 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/layout.md | 329 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/overview.md | 154 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/range.md | 49 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/select.md | 81 | ||||
| -rw-r--r-- | site/content/docs/5.2/forms/validation.md | 380 |
9 files changed, 1920 insertions, 0 deletions
diff --git a/site/content/docs/5.2/forms/checks-radios.md b/site/content/docs/5.2/forms/checks-radios.md new file mode 100644 index 0000000..12f8b00 --- /dev/null +++ b/site/content/docs/5.2/forms/checks-radios.md @@ -0,0 +1,307 @@ +--- +layout: docs +title: Checks and radios +description: Create consistent cross-browser and cross-device checkboxes and radios with our completely rewritten checks component. +group: forms +aliases: "/docs/5.2/forms/checks/" +toc: true +--- + +## Approach + +Browser default checkboxes and radios are replaced with the help of `.form-check`, a series of classes for both input types that improves the layout and behavior of their HTML elements, that provide greater customization and cross browser consistency. Checkboxes are for selecting one or several options in a list, while radios are for selecting one option from many. + +Structurally, our `<input>`s and `<label>`s are sibling elements as opposed to an `<input>` within a `<label>`. This is slightly more verbose as you must specify `id` and `for` attributes to relate the `<input>` and `<label>`. We use the sibling selector (`~`) for all our `<input>` states, like `:checked` or `:disabled`. When combined with the `.form-check-label` class, we can easily style the text for each item based on the `<input>`'s state. + +Our checks use custom Bootstrap icons to indicate checked or indeterminate states. + +## Checks + +{{< example >}} +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="flexCheckDefault"> + <label class="form-check-label" for="flexCheckDefault"> + Default checkbox + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="flexCheckChecked" checked> + <label class="form-check-label" for="flexCheckChecked"> + Checked checkbox + </label> +</div> +{{< /example >}} + +### Indeterminate + +Checkboxes can utilize the `:indeterminate` pseudo class when manually set via JavaScript (there is no available HTML attribute for specifying it). + +{{< example class="bd-example-indeterminate" stackblitz_add_js="true" >}} +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="flexCheckIndeterminate"> + <label class="form-check-label" for="flexCheckIndeterminate"> + Indeterminate checkbox + </label> +</div> +{{< /example >}} + +### Disabled + +Add the `disabled` attribute and the associated `<label>`s are automatically styled to match with a lighter color to help indicate the input's state. + +{{< example class="bd-example-indeterminate" stackblitz_add_js="true" >}} +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="flexCheckIndeterminateDisabled" disabled> + <label class="form-check-label" for="flexCheckIndeterminateDisabled"> + Disabled indeterminate checkbox + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="flexCheckDisabled" disabled> + <label class="form-check-label" for="flexCheckDisabled"> + Disabled checkbox + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="flexCheckCheckedDisabled" checked disabled> + <label class="form-check-label" for="flexCheckCheckedDisabled"> + Disabled checked checkbox + </label> +</div> +{{< /example >}} + +## Radios + +{{< example >}} +<div class="form-check"> + <input class="form-check-input" type="radio" name="flexRadioDefault" id="flexRadioDefault1"> + <label class="form-check-label" for="flexRadioDefault1"> + Default radio + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="radio" name="flexRadioDefault" id="flexRadioDefault2" checked> + <label class="form-check-label" for="flexRadioDefault2"> + Default checked radio + </label> +</div> +{{< /example >}} + +### Disabled + +Add the `disabled` attribute and the associated `<label>`s are automatically styled to match with a lighter color to help indicate the input's state. + +{{< example >}} +<div class="form-check"> + <input class="form-check-input" type="radio" name="flexRadioDisabled" id="flexRadioDisabled" disabled> + <label class="form-check-label" for="flexRadioDisabled"> + Disabled radio + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="radio" name="flexRadioDisabled" id="flexRadioCheckedDisabled" checked disabled> + <label class="form-check-label" for="flexRadioCheckedDisabled"> + Disabled checked radio + </label> +</div> +{{< /example >}} + +## Switches + +A switch has the markup of a custom checkbox but uses the `.form-switch` class to render a toggle switch. Consider using `role="switch"` to more accurately convey the nature of the control to assistive technologies that support this role. In older assistive technologies, it will simply be announced as a regular checkbox as a fallback. Switches also support the `disabled` attribute. + +{{< example >}} +<div class="form-check form-switch"> + <input class="form-check-input" type="checkbox" role="switch" id="flexSwitchCheckDefault"> + <label class="form-check-label" for="flexSwitchCheckDefault">Default switch checkbox input</label> +</div> +<div class="form-check form-switch"> + <input class="form-check-input" type="checkbox" role="switch" id="flexSwitchCheckChecked" checked> + <label class="form-check-label" for="flexSwitchCheckChecked">Checked switch checkbox input</label> +</div> +<div class="form-check form-switch"> + <input class="form-check-input" type="checkbox" role="switch" id="flexSwitchCheckDisabled" disabled> + <label class="form-check-label" for="flexSwitchCheckDisabled">Disabled switch checkbox input</label> +</div> +<div class="form-check form-switch"> + <input class="form-check-input" type="checkbox" role="switch" id="flexSwitchCheckCheckedDisabled" checked disabled> + <label class="form-check-label" for="flexSwitchCheckCheckedDisabled">Disabled checked switch checkbox input</label> +</div> +{{< /example >}} + +## Default (stacked) + +By default, any number of checkboxes and radios that are immediate sibling will be vertically stacked and appropriately spaced with `.form-check`. + +{{< example >}} +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="defaultCheck1"> + <label class="form-check-label" for="defaultCheck1"> + Default checkbox + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="defaultCheck2" disabled> + <label class="form-check-label" for="defaultCheck2"> + Disabled checkbox + </label> +</div> +{{< /example >}} + +{{< example >}} +<div class="form-check"> + <input class="form-check-input" type="radio" name="exampleRadios" id="exampleRadios1" value="option1" checked> + <label class="form-check-label" for="exampleRadios1"> + Default radio + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="radio" name="exampleRadios" id="exampleRadios2" value="option2"> + <label class="form-check-label" for="exampleRadios2"> + Second default radio + </label> +</div> +<div class="form-check"> + <input class="form-check-input" type="radio" name="exampleRadios" id="exampleRadios3" value="option3" disabled> + <label class="form-check-label" for="exampleRadios3"> + Disabled radio + </label> +</div> +{{< /example >}} + +## Inline + +Group checkboxes or radios on the same horizontal row by adding `.form-check-inline` to any `.form-check`. + +{{< example >}} +<div class="form-check form-check-inline"> + <input class="form-check-input" type="checkbox" id="inlineCheckbox1" value="option1"> + <label class="form-check-label" for="inlineCheckbox1">1</label> +</div> +<div class="form-check form-check-inline"> + <input class="form-check-input" type="checkbox" id="inlineCheckbox2" value="option2"> + <label class="form-check-label" for="inlineCheckbox2">2</label> +</div> +<div class="form-check form-check-inline"> + <input class="form-check-input" type="checkbox" id="inlineCheckbox3" value="option3" disabled> + <label class="form-check-label" for="inlineCheckbox3">3 (disabled)</label> +</div> +{{< /example >}} + +{{< example >}} +<div class="form-check form-check-inline"> + <input class="form-check-input" type="radio" name="inlineRadioOptions" id="inlineRadio1" value="option1"> + <label class="form-check-label" for="inlineRadio1">1</label> +</div> +<div class="form-check form-check-inline"> + <input class="form-check-input" type="radio" name="inlineRadioOptions" id="inlineRadio2" value="option2"> + <label class="form-check-label" for="inlineRadio2">2</label> +</div> +<div class="form-check form-check-inline"> + <input class="form-check-input" type="radio" name="inlineRadioOptions" id="inlineRadio3" value="option3" disabled> + <label class="form-check-label" for="inlineRadio3">3 (disabled)</label> +</div> +{{< /example >}} + +## Reverse + +Put your checkboxes, radios, and switches on the opposite side with the `.form-check-reverse` modifier class. + +{{< example >}} +<div class="form-check form-check-reverse"> + <input class="form-check-input" type="checkbox" value="" id="reverseCheck1"> + <label class="form-check-label" for="reverseCheck1"> + Reverse checkbox + </label> +</div> +<div class="form-check form-check-reverse"> + <input class="form-check-input" type="checkbox" value="" id="reverseCheck2" disabled> + <label class="form-check-label" for="reverseCheck2"> + Disabled reverse checkbox + </label> +</div> + +<div class="form-check form-switch form-check-reverse"> + <input class="form-check-input" type="checkbox" id="flexSwitchCheckReverse"> + <label class="form-check-label" for="flexSwitchCheckReverse">Reverse switch checkbox input</label> +</div> +{{< /example >}} + +## Without labels + +Omit the wrapping `.form-check` for checkboxes and radios that have no label text. Remember to still provide some form of accessible name for assistive technologies (for instance, using `aria-label`). See the [forms overview accessibility]({{< docsref "/forms/overview#accessibility" >}}) section for details. + +{{< example >}} +<div> + <input class="form-check-input" type="checkbox" id="checkboxNoLabel" value="" aria-label="..."> +</div> + +<div> + <input class="form-check-input" type="radio" name="radioNoLabel" id="radioNoLabel1" value="" aria-label="..."> +</div> +{{< /example >}} + +## Toggle buttons + +Create button-like checkboxes and radio buttons by using `.btn` styles rather than `.form-check-label` on the `<label>` elements. These toggle buttons can further be grouped in a [button group]({{< docsref "/components/button-group" >}}) if needed. + +### Checkbox toggle buttons + +{{< example >}} +<input type="checkbox" class="btn-check" id="btn-check" autocomplete="off"> +<label class="btn btn-primary" for="btn-check">Single toggle</label> +{{< /example >}} + +{{< example >}} +<input type="checkbox" class="btn-check" id="btn-check-2" checked autocomplete="off"> +<label class="btn btn-primary" for="btn-check-2">Checked</label> +{{< /example >}} + +{{< example >}} +<input type="checkbox" class="btn-check" id="btn-check-3" autocomplete="off" disabled> +<label class="btn btn-primary" for="btn-check-3">Disabled</label> +{{< /example >}} + +{{< callout info >}} +Visually, these checkbox toggle buttons are identical to the [button plugin toggle buttons]({{< docsref "/components/buttons#button-plugin" >}}). However, they are conveyed differently by assistive technologies: the checkbox toggles will be announced by screen readers as "checked"/"not checked" (since, despite their appearance, they are fundamentally still checkboxes), whereas the button plugin toggle buttons will be announced as "button"/"button pressed". The choice between these two approaches will depend on the type of toggle you are creating, and whether or not the toggle will make sense to users when announced as a checkbox or as an actual button. +{{< /callout >}} + +### Radio toggle buttons + +{{< example >}} +<input type="radio" class="btn-check" name="options" id="option1" autocomplete="off" checked> +<label class="btn btn-secondary" for="option1">Checked</label> + +<input type="radio" class="btn-check" name="options" id="option2" autocomplete="off"> +<label class="btn btn-secondary" for="option2">Radio</label> + +<input type="radio" class="btn-check" name="options" id="option3" autocomplete="off" disabled> +<label class="btn btn-secondary" for="option3">Disabled</label> + +<input type="radio" class="btn-check" name="options" id="option4" autocomplete="off"> +<label class="btn btn-secondary" for="option4">Radio</label> +{{< /example >}} + +### Outlined styles + +Different variants of `.btn`, such at the various outlined styles, are supported. + +{{< example >}} +<input type="checkbox" class="btn-check" id="btn-check-outlined" autocomplete="off"> +<label class="btn btn-outline-primary" for="btn-check-outlined">Single toggle</label><br> + +<input type="checkbox" class="btn-check" id="btn-check-2-outlined" checked autocomplete="off"> +<label class="btn btn-outline-secondary" for="btn-check-2-outlined">Checked</label><br> + +<input type="radio" class="btn-check" name="options-outlined" id="success-outlined" autocomplete="off" checked> +<label class="btn btn-outline-success" for="success-outlined">Checked success radio</label> + +<input type="radio" class="btn-check" name="options-outlined" id="danger-outlined" autocomplete="off"> +<label class="btn btn-outline-danger" for="danger-outlined">Danger radio</label> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="form-check-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/forms/floating-labels.md b/site/content/docs/5.2/forms/floating-labels.md new file mode 100644 index 0000000..9ec4fcd --- /dev/null +++ b/site/content/docs/5.2/forms/floating-labels.md @@ -0,0 +1,152 @@ +--- +layout: docs +title: Floating labels +description: Create beautifully simple form labels that float over your input fields. +group: forms +toc: true +--- + +## Example + +Wrap a pair of `<input class="form-control">` and `<label>` elements in `.form-floating` to enable floating labels with Bootstrap's textual form fields. A `placeholder` is required on each `<input>` as our method of CSS-only floating labels uses the `:placeholder-shown` pseudo-element. Also note that the `<input>` must come first so we can utilize a sibling selector (e.g., `~`). + +{{< example >}} +<div class="form-floating mb-3"> + <input type="email" class="form-control" id="floatingInput" placeholder="name@example.com"> + <label for="floatingInput">Email address</label> +</div> +<div class="form-floating"> + <input type="password" class="form-control" id="floatingPassword" placeholder="Password"> + <label for="floatingPassword">Password</label> +</div> +{{< /example >}} + +When there's a `value` already defined, `<label>`s will automatically adjust to their floated position. + +{{< example >}} +<form class="form-floating"> + <input type="email" class="form-control" id="floatingInputValue" placeholder="name@example.com" value="test@example.com"> + <label for="floatingInputValue">Input with value</label> +</form> +{{< /example >}} + +Form validation styles also work as expected. + +{{< example >}} +<form class="form-floating"> + <input type="email" class="form-control is-invalid" id="floatingInputInvalid" placeholder="name@example.com" value="test@example.com"> + <label for="floatingInputInvalid">Invalid input</label> +</form> +{{< /example >}} + +## Textareas + +By default, `<textarea>`s with `.form-control` will be the same height as `<input>`s. + +{{< example >}} +<div class="form-floating"> + <textarea class="form-control" placeholder="Leave a comment here" id="floatingTextarea"></textarea> + <label for="floatingTextarea">Comments</label> +</div> +{{< /example >}} + +To set a custom height on your `<textarea>`, do not use the `rows` attribute. Instead, set an explicit `height` (either inline or via custom CSS). + +{{< example >}} +<div class="form-floating"> + <textarea class="form-control" placeholder="Leave a comment here" id="floatingTextarea2" style="height: 100px"></textarea> + <label for="floatingTextarea2">Comments</label> +</div> +{{< /example >}} + +## Selects + +Other than `.form-control`, floating labels are only available on `.form-select`s. They work in the same way, but unlike `<input>`s, they'll always show the `<label>` in its floated state. **Selects with `size` and `multiple` are not supported.** + +{{< example >}} +<div class="form-floating"> + <select class="form-select" id="floatingSelect" aria-label="Floating label select example"> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + <label for="floatingSelect">Works with selects</label> +</div> +{{< /example >}} + +## Readonly plaintext + +Floating labels also support `.form-control-plaintext`, which can be helpful for toggling from an editable `<input>` to a plaintext value without affecting the page layout. + +{{< example >}} +<div class="form-floating mb-3"> + <input type="email" readonly class="form-control-plaintext" id="floatingEmptyPlaintextInput" placeholder="name@example.com"> + <label for="floatingEmptyPlaintextInput">Empty input</label> +</div> +<div class="form-floating mb-3"> + <input type="email" readonly class="form-control-plaintext" id="floatingPlaintextInput" placeholder="name@example.com" value="name@example.com"> + <label for="floatingPlaintextInput">Input with value</label> +</div> +{{< /example >}} + +## Input groups + +Floating labels also support `.input-group`. + +{{< example >}} +<div class="input-group mb-3"> + <span class="input-group-text">@</span> + <div class="form-floating"> + <input type="text" class="form-control" id="floatingInputGroup1" placeholder="Username"> + <label for="floatingInputGroup1">Username</label> + </div> +</div> +{{< /example >}} + +When using `.input-group` and `.form-floating` along with form validation, the `-feedback` should be placed outside of the `.form-floating`, but inside of the `.input-group`. This means that the feedback will need to be shown using javascript. + +{{< example >}} +<div class="input-group has-validation"> + <span class="input-group-text">@</span> + <div class="form-floating is-invalid"> + <input type="text" class="form-control is-invalid" id="floatingInputGroup2" placeholder="Username" required> + <label for="floatingInputGroup2">Username</label> + </div> + <div class="invalid-feedback"> + Please choose a username. + </div> +</div> +{{< /example >}} + +## Layout + +When working with the Bootstrap grid system, be sure to place form elements within column classes. + +{{< example >}} +<div class="row g-2"> + <div class="col-md"> + <div class="form-floating"> + <input type="email" class="form-control" id="floatingInputGrid" placeholder="name@example.com" value="mdo@example.com"> + <label for="floatingInputGrid">Email address</label> + </div> + </div> + <div class="col-md"> + <div class="form-floating"> + <select class="form-select" id="floatingSelectGrid"> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + <label for="floatingSelectGrid">Works with selects</label> + </div> + </div> +</div> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="form-floating-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/forms/form-control.md b/site/content/docs/5.2/forms/form-control.md new file mode 100644 index 0000000..4d6972d --- /dev/null +++ b/site/content/docs/5.2/forms/form-control.md @@ -0,0 +1,152 @@ +--- +layout: docs +title: Form controls +description: Give textual form controls like `<input>`s and `<textarea>`s an upgrade with custom styles, sizing, focus states, and more. +group: forms +toc: true +--- + +## Example + +{{< example >}} +<div class="mb-3"> + <label for="exampleFormControlInput1" class="form-label">Email address</label> + <input type="email" class="form-control" id="exampleFormControlInput1" placeholder="name@example.com"> +</div> +<div class="mb-3"> + <label for="exampleFormControlTextarea1" class="form-label">Example textarea</label> + <textarea class="form-control" id="exampleFormControlTextarea1" rows="3"></textarea> +</div> +{{< /example >}} + +## Sizing + +Set heights using classes like `.form-control-lg` and `.form-control-sm`. + +{{< example >}} +<input class="form-control form-control-lg" type="text" placeholder=".form-control-lg" aria-label=".form-control-lg example"> +<input class="form-control" type="text" placeholder="Default input" aria-label="default input example"> +<input class="form-control form-control-sm" type="text" placeholder=".form-control-sm" aria-label=".form-control-sm example"> +{{< /example >}} + +## Disabled + +Add the `disabled` boolean attribute on an input to give it a grayed out appearance, remove pointer events, and prevent focusing. + +{{< example >}} +<input class="form-control" type="text" placeholder="Disabled input" aria-label="Disabled input example" disabled> +<input class="form-control" type="text" value="Disabled readonly input" aria-label="Disabled input example" disabled readonly> +{{< /example >}} + +## Readonly + +Add the `readonly` boolean attribute on an input to prevent modification of the input's value. `readonly` inputs can still be focused and selected, while `disabled` inputs cannot. + +{{< example >}} +<input class="form-control" type="text" value="Readonly input here..." aria-label="readonly input example" readonly> +{{< /example >}} + +## Readonly plain text + +If you want to have `<input readonly>` elements in your form styled as plain text, replace `.form-control` with `.form-control-plaintext` to remove the default form field styling and preserve the correct `margin` and `padding`. + +{{< example >}} + <div class="mb-3 row"> + <label for="staticEmail" class="col-sm-2 col-form-label">Email</label> + <div class="col-sm-10"> + <input type="text" readonly class="form-control-plaintext" id="staticEmail" value="email@example.com"> + </div> + </div> + <div class="mb-3 row"> + <label for="inputPassword" class="col-sm-2 col-form-label">Password</label> + <div class="col-sm-10"> + <input type="password" class="form-control" id="inputPassword"> + </div> + </div> +{{< /example >}} + +{{< example >}} +<form class="row g-3"> + <div class="col-auto"> + <label for="staticEmail2" class="visually-hidden">Email</label> + <input type="text" readonly class="form-control-plaintext" id="staticEmail2" value="email@example.com"> + </div> + <div class="col-auto"> + <label for="inputPassword2" class="visually-hidden">Password</label> + <input type="password" class="form-control" id="inputPassword2" placeholder="Password"> + </div> + <div class="col-auto"> + <button type="submit" class="btn btn-primary mb-3">Confirm identity</button> + </div> +</form> +{{< /example >}} + +## File input + +{{< example >}} +<div class="mb-3"> + <label for="formFile" class="form-label">Default file input example</label> + <input class="form-control" type="file" id="formFile"> +</div> +<div class="mb-3"> + <label for="formFileMultiple" class="form-label">Multiple files input example</label> + <input class="form-control" type="file" id="formFileMultiple" multiple> +</div> +<div class="mb-3"> + <label for="formFileDisabled" class="form-label">Disabled file input example</label> + <input class="form-control" type="file" id="formFileDisabled" disabled> +</div> +<div class="mb-3"> + <label for="formFileSm" class="form-label">Small file input example</label> + <input class="form-control form-control-sm" id="formFileSm" type="file"> +</div> +<div> + <label for="formFileLg" class="form-label">Large file input example</label> + <input class="form-control form-control-lg" id="formFileLg" type="file"> +</div> +{{< /example >}} + +## Color + +Set the `type="color"` and add `.form-control-color` to the `<input>`. We use the modifier class to set fixed `height`s and override some inconsistencies between browsers. + +{{< example >}} +<label for="exampleColorInput" class="form-label">Color picker</label> +<input type="color" class="form-control form-control-color" id="exampleColorInput" value="#563d7c" title="Choose your color"> +{{< /example >}} + +## Datalists + +Datalists allow you to create a group of `<option>`s that can be accessed (and autocompleted) from within an `<input>`. These are similar to `<select>` elements, but come with more menu styling limitations and differences. While most browsers and operating systems include some support for `<datalist>` elements, their styling is inconsistent at best. + +Learn more about [support for datalist elements](https://caniuse.com/datalist). + +{{< example >}} +<label for="exampleDataList" class="form-label">Datalist example</label> +<input class="form-control" list="datalistOptions" id="exampleDataList" placeholder="Type to search..."> +<datalist id="datalistOptions"> + <option value="San Francisco"> + <option value="New York"> + <option value="Seattle"> + <option value="Los Angeles"> + <option value="Chicago"> +</datalist> +{{< /example >}} + +## Sass + +### Variables + +`$input-*` are shared across most of our form controls (and not buttons). + +{{< scss-docs name="form-input-variables" file="scss/_variables.scss" >}} + +`$form-label-*` and `$form-text-*` are for our `<label>`s and `.form-text` component. + +{{< scss-docs name="form-label-variables" file="scss/_variables.scss" >}} + +{{< scss-docs name="form-text-variables" file="scss/_variables.scss" >}} + +`$form-file-*` are for file input. + +{{< scss-docs name="form-file-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/forms/input-group.md b/site/content/docs/5.2/forms/input-group.md new file mode 100644 index 0000000..00e9eee --- /dev/null +++ b/site/content/docs/5.2/forms/input-group.md @@ -0,0 +1,316 @@ +--- +layout: docs +title: Input group +description: Easily extend form controls by adding text, buttons, or button groups on either side of textual inputs, custom selects, and custom file inputs. +group: forms +toc: true +--- + +## Basic example + +Place one add-on or button on either side of an input. You may also place one on both sides of an input. Remember to place `<label>`s outside the input group. + +{{< example >}} +<div class="input-group mb-3"> + <span class="input-group-text" id="basic-addon1">@</span> + <input type="text" class="form-control" placeholder="Username" aria-label="Username" aria-describedby="basic-addon1"> +</div> + +<div class="input-group mb-3"> + <input type="text" class="form-control" placeholder="Recipient's username" aria-label="Recipient's username" aria-describedby="basic-addon2"> + <span class="input-group-text" id="basic-addon2">@example.com</span> +</div> + +<label for="basic-url" class="form-label">Your vanity URL</label> +<div class="input-group mb-3"> + <span class="input-group-text" id="basic-addon3">https://example.com/users/</span> + <input type="text" class="form-control" id="basic-url" aria-describedby="basic-addon3"> +</div> + +<div class="input-group mb-3"> + <span class="input-group-text">$</span> + <input type="text" class="form-control" aria-label="Amount (to the nearest dollar)"> + <span class="input-group-text">.00</span> +</div> + +<div class="input-group mb-3"> + <input type="text" class="form-control" placeholder="Username" aria-label="Username"> + <span class="input-group-text">@</span> + <input type="text" class="form-control" placeholder="Server" aria-label="Server"> +</div> + +<div class="input-group"> + <span class="input-group-text">With textarea</span> + <textarea class="form-control" aria-label="With textarea"></textarea> +</div> +{{< /example >}} + +## Wrapping + +Input groups wrap by default via `flex-wrap: wrap` in order to accommodate custom form field validation within an input group. You may disable this with `.flex-nowrap`. + +{{< example >}} +<div class="input-group flex-nowrap"> + <span class="input-group-text" id="addon-wrapping">@</span> + <input type="text" class="form-control" placeholder="Username" aria-label="Username" aria-describedby="addon-wrapping"> +</div> +{{< /example >}} + +## Sizing + +Add the relative form sizing classes to the `.input-group` itself and contents within will automatically resize—no need for repeating the form control size classes on each element. + +**Sizing on the individual input group elements isn't supported.** + +{{< example >}} +<div class="input-group input-group-sm mb-3"> + <span class="input-group-text" id="inputGroup-sizing-sm">Small</span> + <input type="text" class="form-control" aria-label="Sizing example input" aria-describedby="inputGroup-sizing-sm"> +</div> + +<div class="input-group mb-3"> + <span class="input-group-text" id="inputGroup-sizing-default">Default</span> + <input type="text" class="form-control" aria-label="Sizing example input" aria-describedby="inputGroup-sizing-default"> +</div> + +<div class="input-group input-group-lg"> + <span class="input-group-text" id="inputGroup-sizing-lg">Large</span> + <input type="text" class="form-control" aria-label="Sizing example input" aria-describedby="inputGroup-sizing-lg"> +</div> +{{< /example >}} + +## Checkboxes and radios + +Place any checkbox or radio option within an input group's addon instead of text. We recommend adding `.mt-0` to the `.form-check-input` when there's no visible text next to the input. + +{{< example >}} +<div class="input-group mb-3"> + <div class="input-group-text"> + <input class="form-check-input mt-0" type="checkbox" value="" aria-label="Checkbox for following text input"> + </div> + <input type="text" class="form-control" aria-label="Text input with checkbox"> +</div> + +<div class="input-group"> + <div class="input-group-text"> + <input class="form-check-input mt-0" type="radio" value="" aria-label="Radio button for following text input"> + </div> + <input type="text" class="form-control" aria-label="Text input with radio button"> +</div> +{{< /example >}} + +## Multiple inputs + +While multiple `<input>`s are supported visually, validation styles are only available for input groups with a single `<input>`. + +{{< example >}} +<div class="input-group"> + <span class="input-group-text">First and last name</span> + <input type="text" aria-label="First name" class="form-control"> + <input type="text" aria-label="Last name" class="form-control"> +</div> +{{< /example >}} + +## Multiple addons + +Multiple add-ons are supported and can be mixed with checkbox and radio input versions. + +{{< example >}} +<div class="input-group mb-3"> + <span class="input-group-text">$</span> + <span class="input-group-text">0.00</span> + <input type="text" class="form-control" aria-label="Dollar amount (with dot and two decimal places)"> +</div> + +<div class="input-group"> + <input type="text" class="form-control" aria-label="Dollar amount (with dot and two decimal places)"> + <span class="input-group-text">$</span> + <span class="input-group-text">0.00</span> +</div> +{{< /example >}} + +## Button addons + +{{< example >}} +<div class="input-group mb-3"> + <button class="btn btn-outline-secondary" type="button" id="button-addon1">Button</button> + <input type="text" class="form-control" placeholder="" aria-label="Example text with button addon" aria-describedby="button-addon1"> +</div> + +<div class="input-group mb-3"> + <input type="text" class="form-control" placeholder="Recipient's username" aria-label="Recipient's username" aria-describedby="button-addon2"> + <button class="btn btn-outline-secondary" type="button" id="button-addon2">Button</button> +</div> + +<div class="input-group mb-3"> + <button class="btn btn-outline-secondary" type="button">Button</button> + <button class="btn btn-outline-secondary" type="button">Button</button> + <input type="text" class="form-control" placeholder="" aria-label="Example text with two button addons"> +</div> + +<div class="input-group"> + <input type="text" class="form-control" placeholder="Recipient's username" aria-label="Recipient's username with two button addons"> + <button class="btn btn-outline-secondary" type="button">Button</button> + <button class="btn btn-outline-secondary" type="button">Button</button> +</div> +{{< /example >}} + +## Buttons with dropdowns + +{{< example >}} +<div class="input-group mb-3"> + <button class="btn btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + <input type="text" class="form-control" aria-label="Text input with dropdown button"> +</div> + +<div class="input-group mb-3"> + <input type="text" class="form-control" aria-label="Text input with dropdown button"> + <button class="btn btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button> + <ul class="dropdown-menu dropdown-menu-end"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> +</div> + +<div class="input-group"> + <button class="btn btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action before</a></li> + <li><a class="dropdown-item" href="#">Another action before</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + <input type="text" class="form-control" aria-label="Text input with 2 dropdown buttons"> + <button class="btn btn-outline-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false">Dropdown</button> + <ul class="dropdown-menu dropdown-menu-end"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> +</div> +{{< /example >}} + +## Segmented buttons + +{{< example >}} +<div class="input-group mb-3"> + <button type="button" class="btn btn-outline-secondary">Action</button> + <button type="button" class="btn btn-outline-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> + <input type="text" class="form-control" aria-label="Text input with segmented dropdown button"> +</div> + +<div class="input-group"> + <input type="text" class="form-control" aria-label="Text input with segmented dropdown button"> + <button type="button" class="btn btn-outline-secondary">Action</button> + <button type="button" class="btn btn-outline-secondary dropdown-toggle dropdown-toggle-split" data-bs-toggle="dropdown" aria-expanded="false"> + <span class="visually-hidden">Toggle Dropdown</span> + </button> + <ul class="dropdown-menu dropdown-menu-end"> + <li><a class="dropdown-item" href="#">Action</a></li> + <li><a class="dropdown-item" href="#">Another action</a></li> + <li><a class="dropdown-item" href="#">Something else here</a></li> + <li><hr class="dropdown-divider"></li> + <li><a class="dropdown-item" href="#">Separated link</a></li> + </ul> +</div> +{{< /example >}} + +## Custom forms + +Input groups include support for custom selects and custom file inputs. Browser default versions of these are not supported. + +### Custom select + +{{< example >}} +<div class="input-group mb-3"> + <label class="input-group-text" for="inputGroupSelect01">Options</label> + <select class="form-select" id="inputGroupSelect01"> + <option selected>Choose...</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> +</div> + +<div class="input-group mb-3"> + <select class="form-select" id="inputGroupSelect02"> + <option selected>Choose...</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + <label class="input-group-text" for="inputGroupSelect02">Options</label> +</div> + +<div class="input-group mb-3"> + <button class="btn btn-outline-secondary" type="button">Button</button> + <select class="form-select" id="inputGroupSelect03" aria-label="Example select with button addon"> + <option selected>Choose...</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> +</div> + +<div class="input-group"> + <select class="form-select" id="inputGroupSelect04" aria-label="Example select with button addon"> + <option selected>Choose...</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + <button class="btn btn-outline-secondary" type="button">Button</button> +</div> +{{< /example >}} + +### Custom file input + +{{< example >}} +<div class="input-group mb-3"> + <label class="input-group-text" for="inputGroupFile01">Upload</label> + <input type="file" class="form-control" id="inputGroupFile01"> +</div> + +<div class="input-group mb-3"> + <input type="file" class="form-control" id="inputGroupFile02"> + <label class="input-group-text" for="inputGroupFile02">Upload</label> +</div> + +<div class="input-group mb-3"> + <button class="btn btn-outline-secondary" type="button" id="inputGroupFileAddon03">Button</button> + <input type="file" class="form-control" id="inputGroupFile03" aria-describedby="inputGroupFileAddon03" aria-label="Upload"> +</div> + +<div class="input-group"> + <input type="file" class="form-control" id="inputGroupFile04" aria-describedby="inputGroupFileAddon04" aria-label="Upload"> + <button class="btn btn-outline-secondary" type="button" id="inputGroupFileAddon04">Button</button> +</div> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="input-group-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/forms/layout.md b/site/content/docs/5.2/forms/layout.md new file mode 100644 index 0000000..3b27e3f --- /dev/null +++ b/site/content/docs/5.2/forms/layout.md @@ -0,0 +1,329 @@ +--- +layout: docs +title: Layout +description: Give your forms some structure—from inline to horizontal to custom grid implementations—with our form layout options. +group: forms +toc: true +--- + +## Forms + +Every group of form fields should reside in a `<form>` element. Bootstrap provides no default styling for the `<form>` element, but there are some powerful browser features that are provided by default. + +- New to browser forms? Consider reviewing [the MDN form docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form) for an overview and complete list of available attributes. +- `<button>`s within a `<form>` default to `type="submit"`, so strive to be specific and always include a `type`. + +Since Bootstrap applies `display: block` and `width: 100%` to almost all our form controls, forms will by default stack vertically. Additional classes can be used to vary this layout on a per-form basis. + +## Utilities + +[Margin utilities]({{< docsref "/utilities/spacing" >}}) are the easiest way to add some structure to forms. They provide basic grouping of labels, controls, optional form text, and form validation messaging. We recommend sticking to `margin-bottom` utilities, and using a single direction throughout the form for consistency. + +Feel free to build your forms however you like, with `<fieldset>`s, `<div>`s, or nearly any other element. + +{{< example >}} +<div class="mb-3"> + <label for="formGroupExampleInput" class="form-label">Example label</label> + <input type="text" class="form-control" id="formGroupExampleInput" placeholder="Example input placeholder"> +</div> +<div class="mb-3"> + <label for="formGroupExampleInput2" class="form-label">Another label</label> + <input type="text" class="form-control" id="formGroupExampleInput2" placeholder="Another input placeholder"> +</div> +{{< /example >}} + +## Form grid + +More complex forms can be built using our grid classes. Use these for form layouts that require multiple columns, varied widths, and additional alignment options. **Requires the `$enable-grid-classes` Sass variable to be enabled** (on by default). + +{{< example >}} +<div class="row"> + <div class="col"> + <input type="text" class="form-control" placeholder="First name" aria-label="First name"> + </div> + <div class="col"> + <input type="text" class="form-control" placeholder="Last name" aria-label="Last name"> + </div> +</div> +{{< /example >}} + +## Gutters + +By adding [gutter modifier classes]({{< docsref "/layout/gutters" >}}), you can have control over the gutter width in as well the inline as block direction. **Also requires the `$enable-grid-classes` Sass variable to be enabled** (on by default). + +{{< example >}} +<div class="row g-3"> + <div class="col"> + <input type="text" class="form-control" placeholder="First name" aria-label="First name"> + </div> + <div class="col"> + <input type="text" class="form-control" placeholder="Last name" aria-label="Last name"> + </div> +</div> +{{< /example >}} + +More complex layouts can also be created with the grid system. + +{{< example >}} +<form class="row g-3"> + <div class="col-md-6"> + <label for="inputEmail4" class="form-label">Email</label> + <input type="email" class="form-control" id="inputEmail4"> + </div> + <div class="col-md-6"> + <label for="inputPassword4" class="form-label">Password</label> + <input type="password" class="form-control" id="inputPassword4"> + </div> + <div class="col-12"> + <label for="inputAddress" class="form-label">Address</label> + <input type="text" class="form-control" id="inputAddress" placeholder="1234 Main St"> + </div> + <div class="col-12"> + <label for="inputAddress2" class="form-label">Address 2</label> + <input type="text" class="form-control" id="inputAddress2" placeholder="Apartment, studio, or floor"> + </div> + <div class="col-md-6"> + <label for="inputCity" class="form-label">City</label> + <input type="text" class="form-control" id="inputCity"> + </div> + <div class="col-md-4"> + <label for="inputState" class="form-label">State</label> + <select id="inputState" class="form-select"> + <option selected>Choose...</option> + <option>...</option> + </select> + </div> + <div class="col-md-2"> + <label for="inputZip" class="form-label">Zip</label> + <input type="text" class="form-control" id="inputZip"> + </div> + <div class="col-12"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" id="gridCheck"> + <label class="form-check-label" for="gridCheck"> + Check me out + </label> + </div> + </div> + <div class="col-12"> + <button type="submit" class="btn btn-primary">Sign in</button> + </div> +</form> +{{< /example >}} + +## Horizontal form + +Create horizontal forms with the grid by adding the `.row` class to form groups and using the `.col-*-*` classes to specify the width of your labels and controls. Be sure to add `.col-form-label` to your `<label>`s as well so they're vertically centered with their associated form controls. + +At times, you maybe need to use margin or padding utilities to create that perfect alignment you need. For example, we've removed the `padding-top` on our stacked radio inputs label to better align the text baseline. + +{{< example >}} +<form> + <div class="row mb-3"> + <label for="inputEmail3" class="col-sm-2 col-form-label">Email</label> + <div class="col-sm-10"> + <input type="email" class="form-control" id="inputEmail3"> + </div> + </div> + <div class="row mb-3"> + <label for="inputPassword3" class="col-sm-2 col-form-label">Password</label> + <div class="col-sm-10"> + <input type="password" class="form-control" id="inputPassword3"> + </div> + </div> + <fieldset class="row mb-3"> + <legend class="col-form-label col-sm-2 pt-0">Radios</legend> + <div class="col-sm-10"> + <div class="form-check"> + <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios1" value="option1" checked> + <label class="form-check-label" for="gridRadios1"> + First radio + </label> + </div> + <div class="form-check"> + <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios2" value="option2"> + <label class="form-check-label" for="gridRadios2"> + Second radio + </label> + </div> + <div class="form-check disabled"> + <input class="form-check-input" type="radio" name="gridRadios" id="gridRadios3" value="option3" disabled> + <label class="form-check-label" for="gridRadios3"> + Third disabled radio + </label> + </div> + </div> + </fieldset> + <div class="row mb-3"> + <div class="col-sm-10 offset-sm-2"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" id="gridCheck1"> + <label class="form-check-label" for="gridCheck1"> + Example checkbox + </label> + </div> + </div> + </div> + <button type="submit" class="btn btn-primary">Sign in</button> +</form> +{{< /example >}} + +### Horizontal form label sizing + +Be sure to use `.col-form-label-sm` or `.col-form-label-lg` to your `<label>`s or `<legend>`s to correctly follow the size of `.form-control-lg` and `.form-control-sm`. + +{{< example >}} +<div class="row mb-3"> + <label for="colFormLabelSm" class="col-sm-2 col-form-label col-form-label-sm">Email</label> + <div class="col-sm-10"> + <input type="email" class="form-control form-control-sm" id="colFormLabelSm" placeholder="col-form-label-sm"> + </div> +</div> +<div class="row mb-3"> + <label for="colFormLabel" class="col-sm-2 col-form-label">Email</label> + <div class="col-sm-10"> + <input type="email" class="form-control" id="colFormLabel" placeholder="col-form-label"> + </div> +</div> +<div class="row"> + <label for="colFormLabelLg" class="col-sm-2 col-form-label col-form-label-lg">Email</label> + <div class="col-sm-10"> + <input type="email" class="form-control form-control-lg" id="colFormLabelLg" placeholder="col-form-label-lg"> + </div> +</div> +{{< /example >}} + +## Column sizing + +As shown in the previous examples, our grid system allows you to place any number of `.col`s within a `.row`. They'll split the available width equally between them. You may also pick a subset of your columns to take up more or less space, while the remaining `.col`s equally split the rest, with specific column classes like `.col-sm-7`. + +{{< example >}} +<div class="row g-3"> + <div class="col-sm-7"> + <input type="text" class="form-control" placeholder="City" aria-label="City"> + </div> + <div class="col-sm"> + <input type="text" class="form-control" placeholder="State" aria-label="State"> + </div> + <div class="col-sm"> + <input type="text" class="form-control" placeholder="Zip" aria-label="Zip"> + </div> +</div> +{{< /example >}} + +## Auto-sizing + +The example below uses a flexbox utility to vertically center the contents and changes `.col` to `.col-auto` so that your columns only take up as much space as needed. Put another way, the column sizes itself based on the contents. + +{{< example >}} +<form class="row gy-2 gx-3 align-items-center"> + <div class="col-auto"> + <label class="visually-hidden" for="autoSizingInput">Name</label> + <input type="text" class="form-control" id="autoSizingInput" placeholder="Jane Doe"> + </div> + <div class="col-auto"> + <label class="visually-hidden" for="autoSizingInputGroup">Username</label> + <div class="input-group"> + <div class="input-group-text">@</div> + <input type="text" class="form-control" id="autoSizingInputGroup" placeholder="Username"> + </div> + </div> + <div class="col-auto"> + <label class="visually-hidden" for="autoSizingSelect">Preference</label> + <select class="form-select" id="autoSizingSelect"> + <option selected>Choose...</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + </div> + <div class="col-auto"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" id="autoSizingCheck"> + <label class="form-check-label" for="autoSizingCheck"> + Remember me + </label> + </div> + </div> + <div class="col-auto"> + <button type="submit" class="btn btn-primary">Submit</button> + </div> +</form> +{{< /example >}} + +You can then remix that once again with size-specific column classes. + +{{< example >}} +<form class="row gx-3 gy-2 align-items-center"> + <div class="col-sm-3"> + <label class="visually-hidden" for="specificSizeInputName">Name</label> + <input type="text" class="form-control" id="specificSizeInputName" placeholder="Jane Doe"> + </div> + <div class="col-sm-3"> + <label class="visually-hidden" for="specificSizeInputGroupUsername">Username</label> + <div class="input-group"> + <div class="input-group-text">@</div> + <input type="text" class="form-control" id="specificSizeInputGroupUsername" placeholder="Username"> + </div> + </div> + <div class="col-sm-3"> + <label class="visually-hidden" for="specificSizeSelect">Preference</label> + <select class="form-select" id="specificSizeSelect"> + <option selected>Choose...</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + </div> + <div class="col-auto"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" id="autoSizingCheck2"> + <label class="form-check-label" for="autoSizingCheck2"> + Remember me + </label> + </div> + </div> + <div class="col-auto"> + <button type="submit" class="btn btn-primary">Submit</button> + </div> +</form> +{{< /example >}} + +## Inline forms + +Use the `.row-cols-*` classes to create responsive horizontal layouts. By adding [gutter modifier classes]({{< docsref "/layout/gutters" >}}), we'll have gutters in horizontal and vertical directions. On narrow mobile viewports, the `.col-12` helps stack the form controls and more. The `.align-items-center` aligns the form elements to the middle, making the `.form-check` align properly. + +{{< example >}} +<form class="row row-cols-lg-auto g-3 align-items-center"> + <div class="col-12"> + <label class="visually-hidden" for="inlineFormInputGroupUsername">Username</label> + <div class="input-group"> + <div class="input-group-text">@</div> + <input type="text" class="form-control" id="inlineFormInputGroupUsername" placeholder="Username"> + </div> + </div> + + <div class="col-12"> + <label class="visually-hidden" for="inlineFormSelectPref">Preference</label> + <select class="form-select" id="inlineFormSelectPref"> + <option selected>Choose...</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + </div> + + <div class="col-12"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" id="inlineFormCheck"> + <label class="form-check-label" for="inlineFormCheck"> + Remember me + </label> + </div> + </div> + + <div class="col-12"> + <button type="submit" class="btn btn-primary">Submit</button> + </div> +</form> +{{< /example >}} diff --git a/site/content/docs/5.2/forms/overview.md b/site/content/docs/5.2/forms/overview.md new file mode 100644 index 0000000..f38ad90 --- /dev/null +++ b/site/content/docs/5.2/forms/overview.md @@ -0,0 +1,154 @@ +--- +layout: docs +title: Forms +description: Examples and usage guidelines for form control styles, layout options, and custom components for creating a wide variety of forms. +group: forms +toc: true +aliases: "/docs/5.2/forms/" +sections: + - title: Form control + description: Style textual inputs and textareas with support for multiple states. + - title: Select + description: Improve browser default select elements with a custom initial appearance. + - title: Checks & radios + description: Use our custom radio buttons and checkboxes in forms for selecting input options. + - title: Range + description: Replace browser default range inputs with our custom version. + - title: Input group + description: Attach labels and buttons to your inputs for increased semantic value. + - title: Floating labels + description: Create beautifully simple form labels that float over your input fields. + - title: Layout + description: Create inline, horizontal, or complex grid-based layouts with your forms. + - title: Validation + description: Validate your forms with custom or native validation behaviors and styles. +--- + +## Overview + +Bootstrap's form controls expand on [our Rebooted form styles]({{< docsref "/content/reboot#forms" >}}) with classes. Use these classes to opt into their customized displays for a more consistent rendering across browsers and devices. + +Be sure to use an appropriate `type` attribute on all inputs (e.g., `email` for email address or `number` for numerical information) to take advantage of newer input controls like email verification, number selection, and more. + +Here's a quick example to demonstrate Bootstrap's form styles. Keep reading for documentation on required classes, form layout, and more. + +{{< example >}} +<form> + <div class="mb-3"> + <label for="exampleInputEmail1" class="form-label">Email address</label> + <input type="email" class="form-control" id="exampleInputEmail1" aria-describedby="emailHelp"> + <div id="emailHelp" class="form-text">We'll never share your email with anyone else.</div> + </div> + <div class="mb-3"> + <label for="exampleInputPassword1" class="form-label">Password</label> + <input type="password" class="form-control" id="exampleInputPassword1"> + </div> + <div class="mb-3 form-check"> + <input type="checkbox" class="form-check-input" id="exampleCheck1"> + <label class="form-check-label" for="exampleCheck1">Check me out</label> + </div> + <button type="submit" class="btn btn-primary">Submit</button> +</form> +{{< /example >}} + +## Form text + +Block-level or inline-level form text can be created using `.form-text`. + +{{< callout warning >}} +##### Associating form text with form controls + +Form text should be explicitly associated with the form control it relates to using the `aria-describedby` attribute. This will ensure that assistive technologies—such as screen readers—will announce this form text when the user focuses or enters the control. +{{< /callout >}} + +Form text below inputs can be styled with `.form-text`. If a block-level element will be used, a top margin is added for easy spacing from the inputs above. + +{{< example >}} +<label for="inputPassword5" class="form-label">Password</label> +<input type="password" id="inputPassword5" class="form-control" aria-describedby="passwordHelpBlock"> +<div id="passwordHelpBlock" class="form-text"> + Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters, or emoji. +</div> +{{< /example >}} + +Inline text can use any typical inline HTML element (be it a `<span>`, `<small>`, or something else) with nothing more than the `.form-text` class. + +{{< example >}} +<div class="row g-3 align-items-center"> + <div class="col-auto"> + <label for="inputPassword6" class="col-form-label">Password</label> + </div> + <div class="col-auto"> + <input type="password" id="inputPassword6" class="form-control" aria-describedby="passwordHelpInline"> + </div> + <div class="col-auto"> + <span id="passwordHelpInline" class="form-text"> + Must be 8-20 characters long. + </span> + </div> +</div> +{{< /example >}} + +## Disabled forms + +Add the `disabled` boolean attribute on an input to prevent user interactions and make it appear lighter. + +```html +<input class="form-control" id="disabledInput" type="text" placeholder="Disabled input here..." disabled> +``` + +Add the `disabled` attribute to a `<fieldset>` to disable all the controls within. Browsers treat all native form controls (`<input>`, `<select>`, and `<button>` elements) inside a `<fieldset disabled>` as disabled, preventing both keyboard and mouse interactions on them. + +However, if your form also includes custom button-like elements such as `<a class="btn btn-*">...</a>`, these will only be given a style of `pointer-events: none`, meaning they are still focusable and operable using the keyboard. In this case, you must manually modify these controls by adding `tabindex="-1"` to prevent them from receiving focus and `aria-disabled="disabled"` to signal their state to assistive technologies. + +{{< example >}} +<form> + <fieldset disabled> + <legend>Disabled fieldset example</legend> + <div class="mb-3"> + <label for="disabledTextInput" class="form-label">Disabled input</label> + <input type="text" id="disabledTextInput" class="form-control" placeholder="Disabled input"> + </div> + <div class="mb-3"> + <label for="disabledSelect" class="form-label">Disabled select menu</label> + <select id="disabledSelect" class="form-select"> + <option>Disabled select</option> + </select> + </div> + <div class="mb-3"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" id="disabledFieldsetCheck" disabled> + <label class="form-check-label" for="disabledFieldsetCheck"> + Can't check this + </label> + </div> + </div> + <button type="submit" class="btn btn-primary">Submit</button> + </fieldset> +</form> +{{< /example >}} + +## Accessibility + +Ensure that all form controls have an appropriate accessible name so that their purpose can be conveyed to users of assistive technologies. The simplest way to achieve this is to use a `<label>` element, or—in the case of buttons—to include sufficiently descriptive text as part of the `<button>...</button>` content. + +For situations where it's not possible to include a visible `<label>` or appropriate text content, there are alternative ways of still providing an accessible name, such as: + +- `<label>` elements hidden using the `.visually-hidden` class +- Pointing to an existing element that can act as a label using `aria-labelledby` +- Providing a `title` attribute +- Explicitly setting the accessible name on an element using `aria-label` + +If none of these are present, assistive technologies may resort to using the `placeholder` attribute as a fallback for the accessible name on `<input>` and `<textarea>` elements. The examples in this section provide a few suggested, case-specific approaches. + +While using visually hidden content (`.visually-hidden`, `aria-label`, and even `placeholder` content, which disappears once a form field has content) will benefit assistive technology users, a lack of visible label text may still be problematic for certain users. Some form of visible label is generally the best approach, both for accessibility and usability. + +## Sass + +Many form variables are set at a general level to be re-used and extended by individual form components. You'll see these most often as `$input-btn-*` and `$input-*` variables. + +### Variables + +`$input-btn-*` variables are shared global variables between our [buttons]({{< docsref "/components/buttons" >}}) and our form components. You'll find these frequently reassigned as values to other component-specific variables. + +{{< scss-docs name="input-btn-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/forms/range.md b/site/content/docs/5.2/forms/range.md new file mode 100644 index 0000000..5c4f026 --- /dev/null +++ b/site/content/docs/5.2/forms/range.md @@ -0,0 +1,49 @@ +--- +layout: docs +title: Range +description: Use our custom range inputs for consistent cross-browser styling and built-in customization. +group: forms +toc: true +--- + +## Overview + +Create custom `<input type="range">` controls with `.form-range`. The track (the background) and thumb (the value) are both styled to appear the same across browsers. As only Firefox supports "filling" their track from the left or right of the thumb as a means to visually indicate progress, we do not currently support it. + +{{< example >}} +<label for="customRange1" class="form-label">Example range</label> +<input type="range" class="form-range" id="customRange1"> +{{< /example >}} + +## Disabled + +Add the `disabled` boolean attribute on an input to give it a grayed out appearance, remove pointer events, and prevent focusing. + +{{< example >}} +<label for="disabledRange" class="form-label">Disabled range</label> +<input type="range" class="form-range" id="disabledRange" disabled> +{{< /example >}} + +## Min and max + +Range inputs have implicit values for `min` and `max`—`0` and `100`, respectively. You may specify new values for those using the `min` and `max` attributes. + +{{< example >}} +<label for="customRange2" class="form-label">Example range</label> +<input type="range" class="form-range" min="0" max="5" id="customRange2"> +{{< /example >}} + +## Steps + +By default, range inputs "snap" to integer values. To change this, you can specify a `step` value. In the example below, we double the number of steps by using `step="0.5"`. + +{{< example >}} +<label for="customRange3" class="form-label">Example range</label> +<input type="range" class="form-range" min="0" max="5" step="0.5" id="customRange3"> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="form-range-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/forms/select.md b/site/content/docs/5.2/forms/select.md new file mode 100644 index 0000000..7f0c255 --- /dev/null +++ b/site/content/docs/5.2/forms/select.md @@ -0,0 +1,81 @@ +--- +layout: docs +title: Select +description: Customize the native `<select>`s with custom CSS that changes the element's initial appearance. +group: forms +toc: true +--- + +## Default + +Custom `<select>` menus need only a custom class, `.form-select` to trigger the custom styles. Custom styles are limited to the `<select>`'s initial appearance and cannot modify the `<option>`s due to browser limitations. + +{{< example >}} +<select class="form-select" aria-label="Default select example"> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> +</select> +{{< /example >}} + +## Sizing + +You may also choose from small and large custom selects to match our similarly sized text inputs. + +{{< example >}} +<select class="form-select form-select-lg mb-3" aria-label=".form-select-lg example"> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> +</select> + +<select class="form-select form-select-sm" aria-label=".form-select-sm example"> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> +</select> +{{< /example >}} + +The `multiple` attribute is also supported: + +{{< example >}} +<select class="form-select" multiple aria-label="multiple select example"> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> +</select> +{{< /example >}} + +As is the `size` attribute: + +{{< example >}} +<select class="form-select" size="3" aria-label="size 3 select example"> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> +</select> +{{< /example >}} + +## Disabled + +Add the `disabled` boolean attribute on a select to give it a grayed out appearance and remove pointer events. + +{{< example >}} +<select class="form-select" aria-label="Disabled select example" disabled> + <option selected>Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> +</select> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="form-select-variables" file="scss/_variables.scss" >}} diff --git a/site/content/docs/5.2/forms/validation.md b/site/content/docs/5.2/forms/validation.md new file mode 100644 index 0000000..d6d6266 --- /dev/null +++ b/site/content/docs/5.2/forms/validation.md @@ -0,0 +1,380 @@ +--- +layout: docs +title: Validation +description: Provide valuable, actionable feedback to your users with HTML5 form validation, via browser default behaviors or custom styles and JavaScript. +group: forms +toc: true +extra_js: + - src: "/docs/5.2/assets/js/validate-forms.js" + async: true +--- + +{{< callout warning >}} +We are aware that currently the client-side custom validation styles and tooltips are not accessible, since they are not exposed to assistive technologies. While we work on a solution, we'd recommend either using the server-side option or the default browser validation method. +{{< /callout >}} + +## How it works + +Here's how form validation works with Bootstrap: + +- HTML form validation is applied via CSS's two pseudo-classes, `:invalid` and `:valid`. It applies to `<input>`, `<select>`, and `<textarea>` elements. +- Bootstrap scopes the `:invalid` and `:valid` styles to parent `.was-validated` class, usually applied to the `<form>`. Otherwise, any required field without a value shows up as invalid on page load. This way, you may choose when to activate them (typically after form submission is attempted). +- To reset the appearance of the form (for instance, in the case of dynamic form submissions using AJAX), remove the `.was-validated` class from the `<form>` again after submission. +- As a fallback, `.is-invalid` and `.is-valid` classes may be used instead of the pseudo-classes for [server-side validation](#server-side). They do not require a `.was-validated` parent class. +- Due to constraints in how CSS works, we cannot (at present) apply styles to a `<label>` that comes before a form control in the DOM without the help of custom JavaScript. +- All modern browsers support the [constraint validation API](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#the-constraint-validation-api), a series of JavaScript methods for validating form controls. +- Feedback messages may utilize the [browser defaults](#browser-defaults) (different for each browser, and unstylable via CSS) or our custom feedback styles with additional HTML and CSS. +- You may provide custom validity messages with `setCustomValidity` in JavaScript. + +With that in mind, consider the following demos for our custom form validation styles, optional server-side classes, and browser defaults. + +## Custom styles + +For custom Bootstrap form validation messages, you'll need to add the `novalidate` boolean attribute to your `<form>`. This disables the browser default feedback tooltips, but still provides access to the form validation APIs in JavaScript. Try to submit the form below; our JavaScript will intercept the submit button and relay feedback to you. When attempting to submit, you'll see the `:invalid` and `:valid` styles applied to your form controls. + +Custom feedback styles apply custom colors, borders, focus styles, and background icons to better communicate feedback. Background icons for `<select>`s are only available with `.form-select`, and not `.form-control`. + +{{< example >}} +<form class="row g-3 needs-validation" novalidate> + <div class="col-md-4"> + <label for="validationCustom01" class="form-label">First name</label> + <input type="text" class="form-control" id="validationCustom01" value="Mark" required> + <div class="valid-feedback"> + Looks good! + </div> + </div> + <div class="col-md-4"> + <label for="validationCustom02" class="form-label">Last name</label> + <input type="text" class="form-control" id="validationCustom02" value="Otto" required> + <div class="valid-feedback"> + Looks good! + </div> + </div> + <div class="col-md-4"> + <label for="validationCustomUsername" class="form-label">Username</label> + <div class="input-group has-validation"> + <span class="input-group-text" id="inputGroupPrepend">@</span> + <input type="text" class="form-control" id="validationCustomUsername" aria-describedby="inputGroupPrepend" required> + <div class="invalid-feedback"> + Please choose a username. + </div> + </div> + </div> + <div class="col-md-6"> + <label for="validationCustom03" class="form-label">City</label> + <input type="text" class="form-control" id="validationCustom03" required> + <div class="invalid-feedback"> + Please provide a valid city. + </div> + </div> + <div class="col-md-3"> + <label for="validationCustom04" class="form-label">State</label> + <select class="form-select" id="validationCustom04" required> + <option selected disabled value="">Choose...</option> + <option>...</option> + </select> + <div class="invalid-feedback"> + Please select a valid state. + </div> + </div> + <div class="col-md-3"> + <label for="validationCustom05" class="form-label">Zip</label> + <input type="text" class="form-control" id="validationCustom05" required> + <div class="invalid-feedback"> + Please provide a valid zip. + </div> + </div> + <div class="col-12"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="invalidCheck" required> + <label class="form-check-label" for="invalidCheck"> + Agree to terms and conditions + </label> + <div class="invalid-feedback"> + You must agree before submitting. + </div> + </div> + </div> + <div class="col-12"> + <button class="btn btn-primary" type="submit">Submit form</button> + </div> +</form> +{{< /example >}} + +{{< example lang="js" show_preview="false" >}} +{{< js.inline >}} +{{- readFile (path.Join "site/static/docs" .Site.Params.docs_version "assets/js/validate-forms.js") -}} +{{< /js.inline >}} +{{< /example >}} + +## Browser defaults + +Not interested in custom validation feedback messages or writing JavaScript to change form behaviors? All good, you can use the browser defaults. Try submitting the form below. Depending on your browser and OS, you'll see a slightly different style of feedback. + +While these feedback styles cannot be styled with CSS, you can still customize the feedback text through JavaScript. + +{{< example >}} +<form class="row g-3"> + <div class="col-md-4"> + <label for="validationDefault01" class="form-label">First name</label> + <input type="text" class="form-control" id="validationDefault01" value="Mark" required> + </div> + <div class="col-md-4"> + <label for="validationDefault02" class="form-label">Last name</label> + <input type="text" class="form-control" id="validationDefault02" value="Otto" required> + </div> + <div class="col-md-4"> + <label for="validationDefaultUsername" class="form-label">Username</label> + <div class="input-group"> + <span class="input-group-text" id="inputGroupPrepend2">@</span> + <input type="text" class="form-control" id="validationDefaultUsername" aria-describedby="inputGroupPrepend2" required> + </div> + </div> + <div class="col-md-6"> + <label for="validationDefault03" class="form-label">City</label> + <input type="text" class="form-control" id="validationDefault03" required> + </div> + <div class="col-md-3"> + <label for="validationDefault04" class="form-label">State</label> + <select class="form-select" id="validationDefault04" required> + <option selected disabled value="">Choose...</option> + <option>...</option> + </select> + </div> + <div class="col-md-3"> + <label for="validationDefault05" class="form-label">Zip</label> + <input type="text" class="form-control" id="validationDefault05" required> + </div> + <div class="col-12"> + <div class="form-check"> + <input class="form-check-input" type="checkbox" value="" id="invalidCheck2" required> + <label class="form-check-label" for="invalidCheck2"> + Agree to terms and conditions + </label> + </div> + </div> + <div class="col-12"> + <button class="btn btn-primary" type="submit">Submit form</button> + </div> +</form> +{{< /example >}} + +## Server side + +We recommend using client-side validation, but in case you require server-side validation, you can indicate invalid and valid form fields with `.is-invalid` and `.is-valid`. Note that `.invalid-feedback` is also supported with these classes. + +For invalid fields, ensure that the invalid feedback/error message is associated with the relevant form field using `aria-describedby` (noting that this attribute allows more than one `id` to be referenced, in case the field already points to additional form text). + +To fix [issues with border radius](https://github.com/twbs/bootstrap/issues/25110), input groups require an additional `.has-validation` class. + +{{< example >}} +<form class="row g-3"> + <div class="col-md-4"> + <label for="validationServer01" class="form-label">First name</label> + <input type="text" class="form-control is-valid" id="validationServer01" value="Mark" required> + <div class="valid-feedback"> + Looks good! + </div> + </div> + <div class="col-md-4"> + <label for="validationServer02" class="form-label">Last name</label> + <input type="text" class="form-control is-valid" id="validationServer02" value="Otto" required> + <div class="valid-feedback"> + Looks good! + </div> + </div> + <div class="col-md-4"> + <label for="validationServerUsername" class="form-label">Username</label> + <div class="input-group has-validation"> + <span class="input-group-text" id="inputGroupPrepend3">@</span> + <input type="text" class="form-control is-invalid" id="validationServerUsername" aria-describedby="inputGroupPrepend3 validationServerUsernameFeedback" required> + <div id="validationServerUsernameFeedback" class="invalid-feedback"> + Please choose a username. + </div> + </div> + </div> + <div class="col-md-6"> + <label for="validationServer03" class="form-label">City</label> + <input type="text" class="form-control is-invalid" id="validationServer03" aria-describedby="validationServer03Feedback" required> + <div id="validationServer03Feedback" class="invalid-feedback"> + Please provide a valid city. + </div> + </div> + <div class="col-md-3"> + <label for="validationServer04" class="form-label">State</label> + <select class="form-select is-invalid" id="validationServer04" aria-describedby="validationServer04Feedback" required> + <option selected disabled value="">Choose...</option> + <option>...</option> + </select> + <div id="validationServer04Feedback" class="invalid-feedback"> + Please select a valid state. + </div> + </div> + <div class="col-md-3"> + <label for="validationServer05" class="form-label">Zip</label> + <input type="text" class="form-control is-invalid" id="validationServer05" aria-describedby="validationServer05Feedback" required> + <div id="validationServer05Feedback" class="invalid-feedback"> + Please provide a valid zip. + </div> + </div> + <div class="col-12"> + <div class="form-check"> + <input class="form-check-input is-invalid" type="checkbox" value="" id="invalidCheck3" aria-describedby="invalidCheck3Feedback" required> + <label class="form-check-label" for="invalidCheck3"> + Agree to terms and conditions + </label> + <div id="invalidCheck3Feedback" class="invalid-feedback"> + You must agree before submitting. + </div> + </div> + </div> + <div class="col-12"> + <button class="btn btn-primary" type="submit">Submit form</button> + </div> +</form> +{{< /example >}} + +## Supported elements + +Validation styles are available for the following form controls and components: + +- `<input>`s and `<textarea>`s with `.form-control` (including up to one `.form-control` in input groups) +- `<select>`s with `.form-select` +- `.form-check`s + +{{< example >}} +<form class="was-validated"> + <div class="mb-3"> + <label for="validationTextarea" class="form-label">Textarea</label> + <textarea class="form-control" id="validationTextarea" placeholder="Required example textarea" required></textarea> + <div class="invalid-feedback"> + Please enter a message in the textarea. + </div> + </div> + + <div class="form-check mb-3"> + <input type="checkbox" class="form-check-input" id="validationFormCheck1" required> + <label class="form-check-label" for="validationFormCheck1">Check this checkbox</label> + <div class="invalid-feedback">Example invalid feedback text</div> + </div> + + <div class="form-check"> + <input type="radio" class="form-check-input" id="validationFormCheck2" name="radio-stacked" required> + <label class="form-check-label" for="validationFormCheck2">Toggle this radio</label> + </div> + <div class="form-check mb-3"> + <input type="radio" class="form-check-input" id="validationFormCheck3" name="radio-stacked" required> + <label class="form-check-label" for="validationFormCheck3">Or toggle this other radio</label> + <div class="invalid-feedback">More example invalid feedback text</div> + </div> + + <div class="mb-3"> + <select class="form-select" required aria-label="select example"> + <option value="">Open this select menu</option> + <option value="1">One</option> + <option value="2">Two</option> + <option value="3">Three</option> + </select> + <div class="invalid-feedback">Example invalid select feedback</div> + </div> + + <div class="mb-3"> + <input type="file" class="form-control" aria-label="file example" required> + <div class="invalid-feedback">Example invalid form file feedback</div> + </div> + + <div class="mb-3"> + <button class="btn btn-primary" type="submit" disabled>Submit form</button> + </div> +</form> +{{< /example >}} + +## Tooltips + +If your form layout allows it, you can swap the `.{valid|invalid}-feedback` classes for `.{valid|invalid}-tooltip` classes to display validation feedback in a styled tooltip. Be sure to have a parent with `position: relative` on it for tooltip positioning. In the example below, our column classes have this already, but your project may require an alternative setup. + +{{< example >}} +<form class="row g-3 needs-validation" novalidate> + <div class="col-md-4 position-relative"> + <label for="validationTooltip01" class="form-label">First name</label> + <input type="text" class="form-control" id="validationTooltip01" value="Mark" required> + <div class="valid-tooltip"> + Looks good! + </div> + </div> + <div class="col-md-4 position-relative"> + <label for="validationTooltip02" class="form-label">Last name</label> + <input type="text" class="form-control" id="validationTooltip02" value="Otto" required> + <div class="valid-tooltip"> + Looks good! + </div> + </div> + <div class="col-md-4 position-relative"> + <label for="validationTooltipUsername" class="form-label">Username</label> + <div class="input-group has-validation"> + <span class="input-group-text" id="validationTooltipUsernamePrepend">@</span> + <input type="text" class="form-control" id="validationTooltipUsername" aria-describedby="validationTooltipUsernamePrepend" required> + <div class="invalid-tooltip"> + Please choose a unique and valid username. + </div> + </div> + </div> + <div class="col-md-6 position-relative"> + <label for="validationTooltip03" class="form-label">City</label> + <input type="text" class="form-control" id="validationTooltip03" required> + <div class="invalid-tooltip"> + Please provide a valid city. + </div> + </div> + <div class="col-md-3 position-relative"> + <label for="validationTooltip04" class="form-label">State</label> + <select class="form-select" id="validationTooltip04" required> + <option selected disabled value="">Choose...</option> + <option>...</option> + </select> + <div class="invalid-tooltip"> + Please select a valid state. + </div> + </div> + <div class="col-md-3 position-relative"> + <label for="validationTooltip05" class="form-label">Zip</label> + <input type="text" class="form-control" id="validationTooltip05" required> + <div class="invalid-tooltip"> + Please provide a valid zip. + </div> + </div> + <div class="col-12"> + <button class="btn btn-primary" type="submit">Submit form</button> + </div> +</form> +{{< /example >}} + +## Sass + +### Variables + +{{< scss-docs name="form-feedback-variables" file="scss/_variables.scss" >}} + +### Mixins + +Two mixins are combined together, through our [loop](#loop), to generate our form validation feedback styles. + +{{< scss-docs name="form-validation-mixins" file="scss/mixins/_forms.scss" >}} + +### Map + +This is the validation Sass map from `_variables.scss`. Override or extend this to generate different or additional states. + +{{< scss-docs name="form-validation-states" file="scss/_variables.scss" >}} + +Maps of `$form-validation-states` can contain three optional parameters to override tooltips and focus styles. + +### Loop + +Used to iterate over `$form-validation-states` map values to generate our validation styles. Any modifications to the above Sass map will be reflected in your compiled CSS via this loop. + +{{< scss-docs name="form-validation-states-loop" file="scss/forms/_validation.scss" >}} + +### Customizing + +Validation states can be customized via Sass with the `$form-validation-states` map. Located in our `_variables.scss` file, this Sass map is how we generate the default `valid`/`invalid` validation states. Included is a nested map for customizing each state's color, icon, tooltip color, and focus shadow. While no other states are supported by browsers, those using custom styles can easily add more complex form feedback. |