Getting Labels in JavaScript

Static Labels

Static labels are defined in one string, such as "$Label.c.task_mode_today". The framework parses static labels in markup or JavaScript code and sends the labels to the client when the component is loaded. A server trip isn’t required to resolve the label.

Use $A.get() to retrieve static labels in JavaScript code. For example:

var staticLabel = $A.get("$Label.c.task_mode_today");
component.set("v.mylabel", staticLabel);

You can also retrieve label values using Apex code and send them to the component via JavaScript code. For more information, see Getting Labels in Apex.

Dynamic Labels

$A.get(labelReference) must be able to resolve the label reference at compile time, so that the label values can be sent to the client along with the component definition.

If you must defer label resolution until runtime, you can dynamically create labels in JavaScript code. This technique can be useful when you need to use a label, but which specific label isn’t known until runtime.

// Assume the day variable is dynamically generated
// earlier in the code
// THIS CODE WON’T WORK
var dynamicLabel = $A.get("$Label.c." + day);

If the label is already known on the client, $A.get() displays the label. If the value is not known, an empty string is displayed in production mode, or a placeholder value showing the label key is displayed in debug mode.

Using $A.get()with a label that can't be determined at runtime means that dynamicLabel is an empty string, and won’t be updated to the retrieved value. Since the label, "$Label.c." + day, is dynamically generated, the framework can’t parse it or send it to the client when the component is requested.

There are a few alternative approaches to using $A.get() so that you can work with dynamically generated labels.

If your component uses a known set of dynamically constructed labels, you can avoid a server roundtrip for the labels by adding a reference to the labels in a JavaScript resource. The framework sends these labels to the client when the component is requested. For example, if your component dynamically generates $Label.c.task_mode_today and $Label.c.task_mode_tomorrow label keys, you can add references to the labels in a comment in a JavaScript resource, such as a client-side controller or helper.

// hints to ensure labels are preloaded
// $Label.c.task_mode_today
// $Label.c.task_mode_tomorrow

If your code dynamically generates many labels, this approach doesn’t scale well.

If you don’t want to add comment hints for all the potential labels, the alternative is to use $A.getReference(). This approach comes with the added cost of a server trip to retrieve the label value.

This example dynamically constructs the label value by calling $A.getReference() and updates a tempLabelAttr component attribute with the retrieved label.

var labelSubStr = "task_mode_today";
var labelReference = $A.getReference("$Label.c." + labelSubStr);
cmp.set("v.tempLabelAttr", labelReference);
var dynamicLabel = cmp.get("v.tempLabelAttr");

$A.getReference() returns a reference to the label. This isn’t a string, and you shouldn’t treat it like one. You never get a string label directly back from $A.getReference().

Instead, use the returned reference to set a component’s attribute value. Our code does this in cmp.set("v.tempLabelAttr", labelReference);.

When the label value is asynchronously returned from the server, the attribute value is automatically updated as it’s a reference. The component is rerendered and the label value displays.