Forms

Ask a question Design guidelines

Summary

Forms are used to collect user input and configure options of a task the user is completing.

Status

API status: general
Included in AUI core? Yes. You do not need to explicitly require the web resource key.
Web resource key: com.atlassian.auiplugin:aui-forms
AMD Module key: N/A
Experimental API: 1
General API: 3

Examples

Default width input of a required field
Error message here
Long width input
Short width input
Disable field input
help
Medium width input
Medium-long width input

Top labels

Dropdowns and multi select

Dropdowns and multi select
Multi select description

Textarea

Textarea Legend
Cancel

Radio buttons

Radio buttons

Checkboxes

Checkboxes

File upload

File upload

Code

HTML

Forms are constructed with a root element (form.aui), containers (commonly for rows), then various input or button types within those containers.

Commonly, there will be a set of fieldsets and field group elements (depending on the input type contained); and in almost all cases a buttons container at the end. Remember all inputs should have a label, it makes them more usable and accessible.

AخA
 
<form ... class="aui">
    <div class="field-group">...</div>
    <div class="field-group">...</div>
    <div class="buttons-container">
        <div class="buttons">...</div>
    </div>
</form>

A simple example including a required field:

 
<form class="aui">
    <div class="field-group">
        <label for="comment-email">Email
            <span class="aui-icon icon-required">(required)</span></label>
        <input class="text medium-field" type="text"
               id="comment-email" name="comment-email" placeholder="you@example.com">
        <div class="description">Your
            primary email address.</div>
    </div>
    <div class="field-group">
        <label for="comment-input">Comment</label>
        <textarea class="textarea" name="comment-input"
                  id="comment-input" placeholder="Your comment here..."></textarea>
    </div>
    <div class="buttons-container">
        <div class="buttons">
            <input class="button submit" type="submit" value="Save" id="comment-save-button">
            <a class="cancel" href="#">Cancel</a>
        </div>
    </div>
</form>

Text inputs

 
<form class="aui">
    <div class="field-group">
        <label for="text-input">Default field<span class="aui-icon icon-required">required</span></label>
        <input class="text" type="text" id="text-input" name="text-input" title="Text input">
        <div class="description">Default
            width input of a required field</div>
    </div>
</form>

Textareas

 
<form class="aui">
    <fieldset>
        <legend><span>Leave a comment</span></legend>
        <div class="field-group">
            <label for="textarea-id">Comment</label>
            <textarea class="textarea" name="comment" id="textarea-id" placeholder="Your comment here..."></textarea>
        </div>
    </fieldset>
</form>

Radio Buttons

 
<form class="aui">
    <fieldset class="group">
        <legend><span>Radio
        buttons</span></legend>
        <div class="radio">
            <input class="radio" type="radio" checked="checked"
                   name="radiobuttons" id="radioButtonOne">
            <label for="radioButtonOne">Save as a blog post</label>
        </div>
        <div class="radio">
            <input class="radio" type="radio"
                   name="radiobuttons" id="radioButtonTwo">
            <label for="radioButtonTwo">Save as a page</label>
        </div>
        <div class="radio">
            <input class="radio" type="radio"
                   name="radiobuttons" id="radioButtonThree">
            <label for="radioButtonThree">Save to your drafts</label>
        </div>
    </fieldset>
</form>

Checkboxes

​x
 
<form class="aui">
    <fieldset class="group">
        <legend><span>Description of the set of checkboxes</span></legend>
        <div class="checkbox">
            <input class="checkbox" type="checkbox" name="checkBoxOne" id="checkBoxOne">
            <label for="checkBoxOne">Receive email</label>
        </div>
        <div class="checkbox">
            <input class="checkbox" type="checkbox" name="checkBoxTwo" id="checkBoxTwo">
            <label for="checkBoxTwo">Receive push notification</label>
        </div>
​
        <input class="checkbox" type="checkbox" name="checkBoxThree" id="checkBoxThree">
        <label for="checkBoxThree">Receive in-app notification</label>
    </fieldset>
</form>

Select

 
<form class="aui">
    <div class="field-group">
        <label for="select-example">Dropdown</label>
        <select class="select" id="select-example" name="select-example">
            <option>Select</option>
            <option>Option 1</option>
            <option>Option 2</option>
            <optgroup label="Group 1">
                <option>Option one</option>
                <option>Option two</option>
            </optgroup>
            <option>Option 3</option>
            <option>Option 4</option>
        </select>
    </div>
</form>

Multiselect

 
<form class="aui">
    <div class="field-group">
        <label for="multiselect">Multi select</label>
        <select class="multi-select" size="4" multiple="multiple" id="multiselect" name="multiselect">
            <option>option one</option>
            <option>option two</option>
            <option>option three</option>
            <option>option four</option>
            <option>option five</option>
            <option>option six</option>
        </select>
    </div>
</form>

File upload

 
<form class="aui">
    <fieldset>
        <legend><span>File upload</span></legend>
        <div class="field-group">
            <label for="file-upload-example">Upload
                file</label>
            <input class="upfile" type="file" id="file-upload-example" name="file-upload-example">
        </div>
    </fieldset>
</form>

Disabled field

 
<form class="aui">
    <div class="field-group">
        <label for="disabled-field-id">Disabled
            field</label>
        <input class="text" type="text" id="disabled-field-id" name="nameoffield" disabled>
    </div>
</form>

Required field

Note AUI provides the visual style only, you will need to implement validation:

 
<form class="aui">
    <div class="field-group">
        <label for="required-input">Field<span class="aui-icon icon-required">
    required</span></label>
        <input id="required-input" type="text" class="text">
    </div>
</form>

Error

 
<form class="aui">
    <div class="field-group">
        <input type="text" class="text">
        <div class="error">Error message here</div>
    </div>
</form>

Description

Descriptions go just after their input. They should only be used for non-critical, supplementary text. Critical information must go in the label:

 
<form class="aui">
    <div class="field-group">
        <input type="text" class="text">
        <div class="description">Some
            extra info that is nice to know but the user can get by without
            it.</div>
    </div>
</form>

JavaScript

Inline help

Forms include the option for an inline help field, which is hidden on load and toggled with JavaScript.

 
AJS.$(document).ready(function(){
    AJS.inlineHelp();
});
 
<form action="#" method="post" class="aui">
    <label for="inline-help-example">First
        name<span class="aui-icon icon-required"></span></label>
    <input class="text" type="text" id="inline-help-example" name="inline-help-example">
    <span class="aui-icon icon-inline-help"><span>Help</span></span>
    <span class="field-help hidden">This
    text will be toggled if the user clicks the help
    icon.</span>
</form>

Options

Form layouts

The overall layout of the form can be chosen by adding a class to the root element:

  • default, shorter labels (no additional class) - standard layout has narrow labels to the left of inputs.
  • long-label (class="aui long-label") - makes the labels wider.
  • top-label (class="aui top-label") – Places labels above form elements (except radios and checkboxes where the label remains to the right of the input). This style is used for forms in narrow spaces.
  • unsectioned (class="aui unsectioned") – Used for shorter forms that don't require breaking up by section.
 
<form class="aui top-label">
    <fieldset class="top-label">
        <div class="field-group top-label">
            <label for="toplabelfieldexample">Search users</label>
            <input class="text" type="text" id="toplabelfieldexample" name="toplabelfieldexample">
        </div>
    </fieldset>
</form>

Form input widths

You can increase the width of an input (note this is separate from the width of the label, controlled by form layouts) by adding a class to the input:

  • Short: class="short-field"
  • Medium: class="medium-field"
  • Medium-long: class="medium-long-field"
  • Long: class="long-field"
  • Full width: class="full-width-field" (this will make the field expand to the full available width)

For example, to set a long field:

 
<form class="aui">
    <label for="longfieldexample">Search users</label>
    <input class="text long-field" type="text" id="longfieldexample" name="longfieldexample">
</form>