Learn about the guidelines on using the base Lightning components.
We recommend that you don't depend on the markup of a Lightning component as its internals
can change in the future. For example, using cmp.get("v.body") and examining the DOM elements can cause issues in your code if
the component markup change down the road. With LockerService enforced, you can’t traverse the
DOM for components you don't own. Instead of accessing the DOM tree, take advantage of value
binding with component attributes and use component methods that are available to you. For
example, to get an attribute on a component, use cmp.find("myInput").get("v.name") instead of cmp.find("myInput").getElement().name. The latter doesn’t work if you
don’t have access to the component, such as a component in another namespace.
Many of the base Lightning
components are still evolving and the following considerations can help you while you’re
building your apps.
- lightning:buttonMenu (Beta)
- This component contains menu items that are created only if the button is triggered. You
can’t reference the menu items during initialization or if the button isn’t triggered
yet.
- lightning:formattedDateTime (Beta)
- This component provides fallback behavior in Apple Safari 10 and below. The following
formatting options have exceptions when using the fallback behavior in older browsers.
-
era is not supported.
-
timeZoneName appends GMT for short format, GMT-h:mm or GMT+h:mm for long
format.
-
timeZone supports UTC. If another timezone value is used, lightning:formattedDateTime uses the browser timezone.
- lightning:formattedNumber (Beta)
- This component provides the following fallback behavior in Apple Safari 10 and below.
- If style is set to currency, providing a currencyCode
value that’s different from the locale displays the currency code instead of the
symbol. The following example displays EUR12.34
in fallback mode and €12.34
otherwise.
<lightning:formattedNumber value="12.34" style="currency"
currencyCode="EUR"/>
-
currencyDisplayAs supports symbol only. The following example displays $12.34 in fallback mode only if the currencyCode matches the user’s locale currency and
USD12.34
otherwise.
<lightning:formattedNumber value="12.34" style="currency"
currencyCode="USD" currencyDisplayAs="symbol"/>
- lightning:input (Beta)
- Date pickers
are available in the following components but they don’t inherit the Lightning Design System styling.
- <lightning:input type="date" />
- <lightning:input type="datetime-local"
/>
- Fields for percentage and currency input must specify a step increment of 0.01 as
required by the native
implementation.
<lightning:input type="number" name="percentVal" label="Enter a percentage value" formatter="percent" step="0.01" />
<lightning:input type="number" name="currencyVal" label="Enter a dollar amount" formatter="currency" step="0.01" />
- When working with checkboxes, radio buttons, and toggle switches, use aura:id to group and traverse the array of components.
Grouping them enables you to use get("v.checked") to
determine which elements are checked or unchecked without reaching into the DOM. You can
also use the name and value attributes to identify each component during the iteration. The
following example groups three checkboxes together using aura:id.
<aura:component>
<form>
<fieldset>
<legend>Select your favorite color:</legend>
<lightning:input type="checkbox" label="Red"
name="color1" value="1" aura:id="colors"/>
<lightning:input type="checkbox" label="Blue"
name="color2" value="2" aura:id="colors"/>
<lightning:input type="checkbox" label="Green"
name="color3" value="3" aura:id="colors"/>
</fieldset>
<lightning:button label="Submit" onclick="{!c.submitForm}"/>
</form>
</aura:component>
In
your client-side controller, you can retrieve the array using cmp.find("colors") and inspect the checked values.
- When working with type="file", you must provide
your own server-side logic for uploading files to Salesforce. Read the file using the
FileReader HTML object, and then encode the file contents before sending them to your Apex
controller. In your Apex controller, you can use the EncodingUtil methods to decode the file data. For example, you can use the
Attachment object to upload files to a parent object. In this case, you pass in the base64
encoded file to the Body field to save the file as an
attachment in your Apex controller.
Uploading files using this component is subject to
regular Apex controller limits, which is 1 MB. To accommodate file size increase due to
base64 encoding, we recommend that you set the maximum file size to 750 KB. You must
implement chunking for file size larger than 1 MB. Files uploaded via chunking are
subject to a size limit of 4 MB. For more information, see the Apex
Developer Guide.
- lightning:tab (Beta)
- This component creates its body during runtime. You can’t reference the component during
initialization. Referencing the component using aura:id can return unexpected results, such as the component returning an
undefined value when implementing cmp.find("myComponent").
- lightning:tabset (Beta)
- When you load more tabs than can fit the width of the viewport, the tabset provides
navigation buttons that scrolls horizontally to display the overflow tabs.