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:

1var staticLabel = $A.get("$Label.c.task_mode_today");

Dynamic Labels

You can dynamically create labels in JavaScript code. This technique can be useful when you need to use a label that is not known until runtime when it’s dynamically generated.

1// Assume the day variable is dynamically generated
2// earlier in the code
3// THIS CODE WON’T WORK
4var 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.

Since the label, "$Label.c." + day", is dynamically generated, the framework can’t parse it and send it to the client when the component is requested. dynamicLabel is an empty string, which isn’t what you want!

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.

1// hints to ensure labels are preloaded
2// $Label.Related_Lists.task_mode_today
3// $Label.Related_Lists.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.

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

$A.getReference() returns a reference to the label. You never get a string label directly back from $A.getReference().

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.

Dynamically Replacing Label Parameters

If a label value includes a placeholder parameter, such as {0}, use $A.util.format() to replace the parameters with dynamic values. Let’s look at an example with a $Label.Balance.Points label with a value of Your balance is {0} points.

1var placeholderLabel = $A.get("$Label.Balance.Points");
2
3// assuming actualPoints was set earlier in the code
4// $A.util.format() replaces {0} with actualPoints
5var balancePoints = $A.util.format(placeholderLabel, actualPoints);
6if (cmp.isValid()) {
7    cmp.set("v.points", balancePoints);
8}