Form Group

Usage Style Code
Form Groups help give context to a particular form input such as a Textfield. They allow for grouping labels and their inputs for consistent form design. You will stack Form Groups to build an entire Form.

General Guidelines

Form Groups are used as the building blocks of a form. They separate the form into sections of freeform data entry fields.

Form Groups can consist of:

  • Label
  • Optional (in parenthesis)
  • Input Field
  • Placement text (within the field)
  • Help text (below the input field)
  • Action Buttons (when needed)

Voice and Tone

Labels should be clear and concise. They display in words the type of input the corresponding field requires.

The user should understand what they have to enter into the Input Field. Use placement text to provide a guide for the user with more instruction on the type of data they need to enter (for example: Enter amount, or Enter last 4 digits of card).

Grammar and Mechanics

  • Labels are title case
  • Placement text in input fields are sentence case (exception: with formal names or titles, use title case)
  • Labels and placement text do not have punctuation
  • Labels should be limited to one or two words. If the label is more complicated and more words are necessary, use reassuring language, sometimes asking a question)
  • Use of the term optional is lower case and italicized

Layout and Usage

By default stacked labels are used, but we also support inline layout. Stacked labels make forms easier to scan and faster to complete. To learn more see Forms in UI Patterns.

Optional Fields

The majority of out input fields are required. When a field is NOT required an “Optional” label is displayed.

Usage

Configurations When
Labels are stacked In the majority of layouts, when used in a form.
Labels are inline Primarily when used for desktop, where there is more horizontal space available.
Labels are required Always label input fields.
Use (optional) beside the label When input fields are optional for the user to fill out.
Action Buttons are left-aligned (with the primary action on the left) When Form Groups are stacked for desktop.
Action Buttons are below the Form Group (with the primary action centered and placed on top of any secondary actions) When Form Groups are stacked for mobile.

Do's and Don'ts

Do show important requirements as help text under input field
Do use clear language to tell user what they need to enter
Do lead with strong verbs that encourage action for the user
Don't use long labels
Don't use an asterick to show something is required
Don't make user delete placeholder text
Form Groups help give context to a particular form input such as a Textfield. They allow for grouping labels and their inputs for consistent form design. You will stack Form Groups to build an entire Form.

States

Decorators

Spacing, Color, and Typography

Form Groups help give context to a particular form input such as a Textfield. They allow for grouping labels and their inputs for consistent form design. You will stack Form Groups to build an entire Form.

Examples

For details on when to use this component, please see the Usage tab.

When attaching a submit handler to the form, attach the listener to the <form> element as a submit event, not as a click handler on the <button> element. Doing the latter does not allow the ability to submit on enter from within a textfield or other form element.

Stacked Form Group

<form>
    <div class="iris-form-group iris-form-group--stacked">
        <label class="iris-form-group__label" for="frm_textfield_1">First Name</label>
        <div class="iris-form-group__field">
            <div class="iris-textfield">
                <input id="frm_textfield_1" type="text" class="iris-textfield__input" placeholder="e.g. John" aria-required="true" required />
            </div>
        </div>
    </div>
    <div class="iris-form-group iris-form-group--stacked">
        <label class="iris-form-group__label" for="frm_textfield_2">Last Name</label>
        <div class="iris-form-group__field">
            <div class="iris-textfield">
                <input id="frm_textfield_2" type="text" class="iris-textfield__input" placeholder="e.g. Doe" aria-required="true" required />
            </div>
        </div>
    </div>
    <div class="iris-form-group iris-form-group--stacked">
        <label class="iris-form-group__label" for="frm_textfield_5">Suffix <span class="iris-form-note">(optional)</span></label>
        <div class="iris-form-group__field">
            <div class="iris-textfield" data-size="small">
                <input id="frm_textfield_5" type="text" class="iris-textfield__input" placeholder="e.g. Sr" />
            </div>
        </div>
    </div>
    <div class="button-group">
        <button type="submit" class="iris-button iris-button--primary " data-size="full-width" >
            <span class="iris-button__text">Submit</span>
        </button>
    </div>
</form>

Inline Form Group

When using the Inline Form Group, you should use the decorators of large, medium, or small. Note, Inline Field Groups will be stacked on a mobile screen.

<form>
    <div class="iris-form-group iris-form-group--inline" data-size="large">
        <label class="iris-form-group__label" for="frm_textfield_3">First Name</label>
        <div class="iris-form-group__field">
            <div class="iris-textfield" >
                <input id="frm_textfield_3" type="text" class="iris-textfield__input" placeholder="e.g. John" aria-required="true" required/>
            </div>
        </div>
    </div>
    <div class="iris-form-group iris-form-group--inline" data-size="large">
        <label class="iris-form-group__label" for="frm_textfield_4">Last Name</label>
        <div class="iris-form-group__field">
            <div class="iris-textfield">
                <input id="frm_textfield_4" type="text" class="iris-textfield__input" placeholder="e.g. Doe" aria-required="true" required/>
            </div>
        </div>
    </div>
    <div class="iris-form-group iris-form-group--inline" data-size="large">
        <label class="iris-form-group__label" for="frm_textfield_5">Suffix <span class="iris-form-note">(optional)</span></label>
        <div class="iris-form-group__field">
            <div class="iris-textfield" data-size="small">
                <input id="frm_textfield_5" type="text" class="iris-textfield__input" placeholder="e.g. Sr" />
            </div>
        </div>
    </div>
    <div class="button-group">
        <button type="submit" class="iris-button iris-button--primary " data-size="full-width" >
            <span class="iris-button__text">Submit</span>
        </button>
    </div>
</form>

Multiple Fields in One Group

Use a Form Group Set when you need to group multiple fields together as a single entity. A Group Set has all the same features as a Form Group. You can group multiple Form Groups into a Group Set.

Address
  • Alabama
  • Alaska
  • Arizona
  • Arkansas
  • California
  • Colorado
  • Connecticut
  • Delaware
  • District Of Columbia
  • Florida
  • Georgia
  • Hawaii
  • Idaho
  • Illinois
  • Indiana
  • Iowa
  • Kansas
  • Kentucky
  • Louisiana
  • Maine
  • Maryland
  • Massachusetts
  • Michigan
  • Minnesota
  • Mississippi
  • Missouri
  • Montana
  • Nebraska
  • Nevada
  • New Hampshire
  • New Jersey
  • New Mexico
  • New York
  • North Carolina
  • North Dakota
  • Ohio
  • Oklahoma
  • Oregon
  • Pennsylvania
  • Rhode Island
  • South Carolina
  • South Dakota
  • Tennessee
  • Texas
  • Utah
  • Vermont
  • Virginia
  • Washington
  • West Virginia
  • Wisconsin
  • Wyoming
<form>
    <fieldset class="iris-form-groupset iris-form-groupset--inline" data-size="large">
        <div class="iris-form-groupset__container">
            <legend class="iris-form-groupset__label">Address</legend>
            <div class="iris-form-groupset__groups">
                <div class="iris-form-group iris-form-group--stacked">
                    <label for="frm_textfield_street_1" class="iris-form-group__label">Street 1</label>
                    <div class="iris-form-group__field">
                        <div class="iris-textfield">
                            <input id="frm_textfield_street_1" type="text" class="iris-textfield__input" placeholder="e.g. Street 1" aria-required="true"/>
                        </div>
                    </div>
                </div>
                <div class="iris-form-group iris-form-group--stacked">
                    <label for="frm_textfield_street_2" class="iris-form-group__label">Street 2 <span class="iris-form-note">(optional)</span></label>
                    <div class="iris-form-group__field">
                        <div class="iris-textfield">
                            <input id="frm_textfield_street_2" type="text" class="iris-textfield__input" placeholder="e.g. Street 2" />
                        </div>
                    </div>
                </div>
                <div class="container-fluid pad-x--0">
                    <div class="row ">
                        <div class="col-4">
                            <div class="iris-form-group iris-form-group--stacked">
                                <label for="frm_textfield_city" class="iris-form-group__label">City</label>
                                <div class="iris-form-group__field">
                                    <div class="iris-textfield">
                                        <input id="frm_textfield_city" type="text" class="iris-textfield__input" placeholder="City" aria-required="true"/>
                                    </div>
                                </div>
                            </div>
                        </div>
                        <div class="col-4">
                            <div class="iris-form-group iris-form-group--stacked">
                                <label for="frm_dropdown_state" class="iris-form-group__label">State</label>
                                <div class="iris-form-group__field">
                                    <div class="iris-dropdown" id="frm_dropdown_state" name="dropdown" placeholder="Select a State.">
                                        <ul class="iris-options-list">
                                            <li class="iris-option" data-value="AL">Alabama</li>
                                            <!--... More states ...-->
                                        </ul>
                                    </div>
                                </div>
                            </div>
                        </div>
                        <div class="col-4">
                            <div class="iris-form-group iris-form-group--stacked">
                                <label for="frm_textfield_zip" class="iris-form-group__label">Zip Code</label>
                                <div class="iris-form-group__field">
                                    <div class="iris-textfield">
                                        <input id="frm_textfield_zip" type="text" class="iris-textfield__input" placeholder="Zip" aria-required="true" />
                                    </div>
                                </div>
                            </div>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </fieldset>
    <div class="button-group">
        <button type="submit" class="iris-button iris-button--primary " data-size="full-width" >
            <span class="iris-button__text">Submit</span>
        </button>
    </div>
</form>

Radio Buttons and Checkboxes

These elements should be treated in most cases like multiple fields in one group. You will need to use a Form Group Set.

Did you authorize or participate in the transaction above?
Send receipt to: 
<form>
    <div class="iris-form-group iris-form-group--stacked" data-size="large">
        <label class="iris-form-group__label" for="frm_transaction_amount">Transaction Amount</label>
        <div class="iris-form-group__field">
            <div class="iris-textfield" >
                <input id="frm_transaction_amount" type="text" class="iris-textfield__input" placeholder="Enter an amount in dollars" />
            </div>
        </div>
    </div>
    <fieldset class="iris-form-groupset iris-form-groupset--stacked">
        <div class="iris-form-groupset__container">
            <legend class="iris-form-groupset__label">Did you authorize or participate in the transaction above?</legend>
            <div class="iris-form-groupset__groups">
                <div class="iris-radio">
                    <input class="iris-radio__input" name="authorize-transaction" type="radio" id="authorize_transaction_1" />
                    <label class="iris-radio__label" for="authorize_transaction_1">
                        <span class="iris-radio__content">Yes</span>
                    </label>
                </div>
                <div class="iris-radio">
                    <input class="iris-radio__input" name="authorize-transaction" type="radio" id="authorize_transaction_2" />
                    <label class="iris-radio__label" for="authorize_transaction_2">
                        <span class="iris-radio__content">No</span>
                    </label>
                </div>
            </div>
        </div>
    </fieldset>
    <fieldset class="iris-form-groupset iris-form-groupset--stacked">
        <div class="iris-form-groupset__container">
            <legend class="iris-form-groupset__label">Send receipt to:</legend>
            <div class="iris-form-groupset__groups">
                <div class="iris-checkbox">
                    <input class="iris-checkbox__input" type="checkbox" id="mailto_1" />
                    <label class="iris-checkbox__label" for="mailto_1">
                        <span class="iris-checkbox__content">Email</span>
                    </label>
                </div>
                <div class="iris-checkbox">
                    <input class="iris-checkbox__input" type="checkbox" id="mailto_2" />
                    <label class="iris-checkbox__label" for="mailto_2">
                        <span class="iris-checkbox__content">SMS</span>
                    </label>
                </div>
                <div class="iris-checkbox">
                    <input class="iris-checkbox__input" type="checkbox" id="mailto_3" />
                    <label class="iris-checkbox__label" for="mailto_3">
                        <span class="iris-checkbox__content">Postal</span>
                    </label>
                </div>
            </div>
        </div>
    </fieldset>
    <div class="button-group">
        <button type="submit" class="iris-button iris-button--primary " data-size="full-width" >
            <span class="iris-button__text">Submit</span>
        </button>
    </div>
</form>

Form Group With Nontraditional Fields

If you have your own input type you can easily use a field group to handle those inputs. You can also just stick a value straight in for times when you want to show a read-only style view of the form data.

First Name
John
Last Name
Doe 
<div class="iris-form-group iris-form-group--stacked">
    <span class="iris-form-group__label">First Name</span>
    <div class="iris-form-group__field">
        <span class="iris-form-group__field-value">John</span>
    </div>
</div>
<div class="iris-form-group iris-form-group--stacked">
    <span class="iris-form-group__label">Last Name</span>
    <div class="iris-form-group__field">
        <span class="iris-form-group__field-value">Doe</span>
    </div>
</div>

Form Group With Required Fields

Required fields should not be decorated with an asterisk, but instead all non-required fields should have a label suffix of (Optional). See example below, the First Name field have an aria-required="true" with a required attribute BUT the Last Name field have a label note with the words Optional. 

<form>
    <div class="iris-form-group iris-form-group--stacked">
        <label class="iris-form-group__label" for="frm_textfield_1">First Name</label>
        <div class="iris-form-group__field">
            <div class="iris-textfield">
                <input id="frm_textfield_1" type="text" class="iris-textfield__input" placeholder="e.g. John" aria-required="true" />
            </div>
        </div>
    </div>
    <div class="iris-form-group iris-form-group--stacked">
        <label class="iris-form-group__label" for="frm_textfield_2">Last Name</label>
        <div class="iris-form-group__field">
            <div class="iris-textfield">
                <input id="frm_textfield_2" type="text" class="iris-textfield__input" placeholder="e.g. Doe" aria-required="true" />
            </div>
        </div>
    </div>
    <div class="iris-form-group iris-form-group--stacked">
        <label class="iris-form-group__label" for="frm_textfield_5">Suffix <span class="iris-form-note">(optional)</span></label>
        <div class="iris-form-group__field">
            <div class="iris-textfield" data-size="small">
                <input id="frm_textfield_5" type="text" class="iris-textfield__input" placeholder="e.g. Sr" />
            </div>
        </div>
    </div>
    <div class="button-group">
        <button type="submit" class="iris-button iris-button--primary " data-size="full-width" >
            <span class="iris-button__text">Submit</span>
        </button>
    </div>
</form>

Accessibility

As always, we want all of the components in the application to be accessible. Please keep the following notes in mind while using this component:

  • Use the for attribute on the iris-form-group__label. This should be tied to the id of the input element.
  • When you need multiple fields tied together use the Form Group Set example. It contains the <fieldset><legend> elements to help with Accessibility.

Variables

The variables used in this component are as follows:

// Text variables
$form-label-text: $mine-shaft;
$form-note-text: $dove-gray;
$form-label-font-size: 1.4rem;
$form-note-font-size: 1.2rem;

Themeability

Nothing is themeable in this component.