form-element
About Form Elements
The Form Element is initialized with slds-form-element and is made up of three primary pieces; a label (slds-form-element__label), a form control container (slds-form-element__control), and a form input element, i.e. <input>.
Form Label
A form label should use either the <label> or <legend> elements with the class slds-form-element__label. Use <legend> when you have a compound form.
<label class="slds-form-element__label" for="unique-id-of-input">Form label</label>Form Control
A form control is a div with the class slds-form-element__control. The control is required to maintain the structure of the Form Element.
<div class="slds-form-element__control">Any form type goes here</div>Form Input Elements
There are many types of input elements that can be used in the Form Element, including inputs, text areas, checkboxes, and radio buttons. Visit the individual component pages for in-depth details of their specific states and visuals.
Accessibility
Labels must have the for attribute applied, and its value must match the ID of the associated form element, like <input id="unique-id-of-input" />. This association ensures that assistive technology informs users about what information to enter where.
Mobile
On mobile devices, such as phones and other devices that have touch as the primary method of interaction, form elements will have an increased size of label and info icon.
Below is a live example of what to expect in that context. No code changes are needed in the Salesforce platform context as this change occurs automatically in the appropriate context. For those users not on the Salesforce platform, these modifications will occur automatically when the secondary touch stylesheet is loaded and the device has touch as the primary method of interaction.
Base
<div class="slds-form-element">
<label class="slds-form-element__label" for="form-element-01">Form Label</label>
<div class="slds-form-element__control">States
View Mode/Static
If a form element requires a view mode or static state, instead of slds-form-element__label being a <label> element, we want to change the element to a <span>. This is because the form is no longer a form but a statically read name and value pair.
The string inside of slds-form-element__control needs to be wrapped in a <div> as well, with the class slds-form-element__static applied to it.
In addition to the structural changes — if the form element is standalone, you can optionally apply slds-form-element__readonly. The class will help spacing and separation between other form elements. This class is required if the form element is in the context of a larger form composition.
<div class="slds-form-element slds-form-element_readonly">
<span class="slds-form-element__label">Status</span>
<div class="slds-form-element__control">Inline Edit
If the form element has inline editable capabilities, the form element will require the class slds-form-element_edit. This will apply styles that help handle the structure of the additional elements, such as the button icon to switch the element out of view mode and into edit mode.
In addition, we want to provide an interaction hint by increasing the contrast of the button icon on hover by adding slds-hint-parent to the form element. The button icon will also require the class slds-button__icon_hint. This will notify the form element that this is the element we want to provide an interaction hint for. For more implementation details, please refer to Button icon with hint on hover
<div class="slds-form-element slds-form-element_edit slds-form-element_readonly slds-hint-parent">
<span class="slds-form-element__label">Status</span>
<div class="slds-form-element__control">Help Text Icon
A form element can have help text that will display in a tooltip when hovering or focusing on an icon.
The icon comes in the form of a button icon so it can receive focus when a user tabs through a form with multiple form elements.
The button icon is required to be wrapped in a <div> with the class slds-form-element__icon and should be placed outside of the <label> element.
<div class="slds-form-element">
<label class="slds-form-element__label" for="form-element-help-01">Status</label>
<div class="slds-form-element__icon">Mobile context changes
Please be aware that in a mobile context form elements with a help text icon will automatically change slightly as shown in the example below. For more details please see the mobile specific documentation above.
Showing tooltip
The help text icon uses a tooltip to show the help text information. Please see Tooltips for implementation details.
<div class="slds-form-element">
<label class="slds-form-element__label" for="tooltip-showing-form-element-help-01">Status</label>
<div class="slds-form-element__icon">Feedback
A form element can have various methods of feedback, such as a required denotation or an inline error message.
Required
When a form element is required, an <abbr> should be injected before the <input> and within the <label> and have the class slds-required.
The <input> element should also have the HTML attribute required or required="". Similarly, if it is disabled, it should have the disabled or disabled="" attribute. Do not use true/false values inside the required or disabled attributes because the mere presence of these attributes signifies the field is required or disabled.
<div class="slds-form-element">
<label class="slds-form-element__label" for="form-element-03">
<abbr class="slds-required" title="required">* </abbr>Form Label</label>Error
If an error has occurred while submitting a form, the form element with an error should provide feedback. The slds-has-error class is placed on the <div class="slds-form-element"> element. Then, the error message for the user is placed in a <div> with the slds-form-element__help class.
Accessibility requirement
When a form element displays feedback notifying the user of an error, the error string should be linked to the element by adding the
aria-describedbyattribute to the<input>. The `aria-describedby` attribute must reference the id of the error message. This configuration allows screen readers to read the associated error message when the invalid field is focused.
<div class="slds-form-element slds-has-error">
<label class="slds-form-element__label" for="form-element-05">
<abbr class="slds-required" title="required">* </abbr>Form Label</label>Layout Variations
If your form has more than one form element, you can switch the direction of slds-form-element__label and slds-form-element__control by applying slds-form-element_stacked for stacked labels and slds-form-element_horizontal for left-aligned labels. For optimal spacing and layout, ensure the slds-form-element class is present on each element within the form.
Stacked
To vertically stack <label> and <input> pairs, place slds-form-element_stacked on the div with the class of slds-form-element for optimal spacing.
<div class="slds-form">
<div class="slds-form-element slds-form-element_stacked">
<label class="slds-form-element__label" for="stacked-input-id-01">Text Input</label>Horizontal
To horizontally align a <label> and <input>, use the slds-form-element_horizontal class on the div with the class of slds-form-element. The slds-form-element__label takes up 33% of the width, and the slds-form-element__control uses the remaining 66%.
<div class="slds-form">
<div class="slds-form-element slds-form-element_horizontal">
<label class="slds-form-element__label" for="horizontal-input-id-01">Text Input</label>Single Column Support
When using slds-form-element_horizontal, you might find that the 33/66% distribution of the label to control might be too much in a single column form when displayed in a larger region. Another scenario where single column support would be useful is when a form element spans 100% while the other form elements in your form are 50/50 split. To reduce the distribution and/or align with 50/50 split form elements, adding the class slds-form-element_1-col to slds-form-element will re-distribute the layout.
Standalone
<div class="slds-form-element slds-form-element_horizontal slds-is-editing slds-form-element_1-col">
<label class="slds-form-element__label" for="single-form-element-id-01">Description</label>
<div class="slds-form-element__control">With 50/50 split
<div class="slds-form" role="list">
<div class="slds-form__row">
<div class="slds-form__item" role="listitem">Compound
A compound form is a grouping of several form elements described by a label/title. The compound form should be implemented as a <fieldset>, where the label/title is implemented as a <legend> element.
The <fieldset> requires the class slds-form-element_compound. This class handles the layout and wrapping of the form elements that are grouped together.
The <legend> element requires the class slds-form-element__legend. Legend elements can only accept a limited amount of CSS properties so this class is there to help manage its layout.
<fieldset class="slds-form-element slds-form-element_compound">
<legend class="slds-form-element__legend slds-form-element__label">Fieldset Label</legend>
<div class="slds-form-element__control">...</div>Rows
Each row of a compound field should be wrapped in a <div> with the class slds-form-element__row.
Fields
Each field inside of a compound row can be explicitly sized by using a sizing class, e.g. slds-size_1-of-2.
<div class="slds-form-element__row">
<div class="slds-size_1-of-2">...</div>
</div><fieldset class="slds-form-element slds-form-element_compound">
<legend class="slds-form-element__legend slds-form-element__label">Location</legend>
<div class="slds-form-element__control">Address
Though an address form is utilizing the slds-form-element_compound class, we need to also add the slds-form-element_address class to the component. We modify some of the behavior of an address form with this class.
<fieldset class="slds-form-element slds-form-element_compound slds-form-element_address">
<legend class="slds-form-element__legend slds-form-element__label">Billing Address</legend>
<div class="slds-form-element__control">Usage Examples
Record Form
A record form is a series of rows created by slds-form__row. Inside of each row contains up to 2 inline-editable form element. Each item inside of slds-form__row is required to be wrapped in a <div> with the class slds-form__item.
Accessibility Requirement
Due to the nature of how the record form is composed, we need to notify screen readers that this is a list by adding
role="list"to theslds-formelement. Every column inside of each row should getrole="listitem"to identify itself as items of the list.
View Mode
When in view/readonly mode, it is required to have the class slds-form-element_readonly on the slds-form-element element. This class will provide styles for scanability and spacing.
If inline-edit mode is enabled, you will also need to add slds-form-element_edit to the slds-form-element to accommodate the space for the edit button icon.
Stacked Alignment
When you want the form elements inside of your record form to be stacked. Each slds-form-element should also get the class slds-form-element_stacked.
<div class="slds-form" role="list">
<div class="slds-form__row">
<div class="slds-form__item" role="listitem">Mobile context changes
Please be aware that in a mobile context form elements within a record form with stacked alignment will automatically change slightly as shown in the example below. For more details please see the mobile specific documentation above.
Horizontal Alignment
By adding the class slds-form-element_horizontal to every slds-form-element, your form can switch from stacked to left-aligned, horizontal labels in order to reduce vertical space.
<div class="slds-form" role="list">
<div class="slds-form__row">
<div class="slds-form__item" role="listitem">Mobile context changes
Please be aware that in a mobile context form elements within a record form with horizontal alignment will automatically change slightly as shown in the example below. For more details please see the mobile specific documentation above.
Edit Mode
When a form switches to edit mode, we need to replace all readonly form elements with their semantic field type form element. The structure remains the same:
<div class="slds-form-element">
<label class="slds-form-element__label" for="unique-form-element-id">My Label</label>
<div class="slds-form-element__control">...</div>The form content found inside of slds-form-element__control should be replaced with the appropriate field type of the view/readonly state.
Stacked Alignment
<div class="slds-form" role="list">
<div class="slds-form__row">
<div class="slds-form__item" role="listitem">Horizontal Alignment
<div class="slds-form" role="list">
<div class="slds-form__row">
<div class="slds-form__item" role="listitem">