Forms are used to collect user input and configure options of a task the user is completing.
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 |
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.
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
<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>
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>
<form class="aui">
<div class="field-group">
<input type="text" class="text">
<div class="error">Error message here</div>
</div>
</form>
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>
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>
The overall layout of the form can be chosen by adding a class to the root element:
class="aui long-label"
) - makes the labels wider.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.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>
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:
class="short-field"
class="medium-field"
class="medium-long-field"
class="long-field"
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>