Custom labels in Salesforce are named, reusable text values, such as error messages, button captions and help text, that you create in Setup and reference from Apex, Lightning web components, Aura, Visualforce and Flow. Because the words live outside the code, you can reword or translate them with Translation Workbench without touching or redeploying the code.
This guide first appeared on our blog in 2021. It was rewritten in November 2026 for Lightning Experience and current Salesforce documentation; the old Salesforce Classic steps are gone. For how custom labels compare with custom settings and custom metadata types, see our guide to Salesforce metadata. If you are new to Setup, our hands-on Salesforce tutorial builds a small app first.
What are custom labels used for?
Use a custom label for any text a user reads that might change or need translating. Typical examples:
- Error and confirmation messages shown by Apex, a Lightning web component or a screen flow.
- Button captions, headings and help text in custom components.
- Text in multilingual apps, where each user should see their own language.
- Text shared by several components, so one change updates every place it appears.
Don't use labels as a general settings store. Values that control behavior, such as thresholds, mappings or endpoints, belong in a custom metadata type, and secrets belong in named credentials.
How do you create a custom label in Salesforce?
You create custom labels in Setup, and you need permission to customize the application to do it. In Lightning Experience:
- Click the gear icon and open Setup.
- In the Quick Find box, enter Custom Labels and select Custom Labels.
- Click New Custom Label. To change an existing label, click Edit next to it.
- Enter a Short Description. This is how admins find the label later, so make it specific, for example "Order submitted confirmation".
- Enter the Name. This is the API name your code uses, such as
Order_Submitted. Check the naming rules below before you save, because code refers to this name. - Optionally enter Categories, comma-separated words such as orders, confirmation, so labels are easier to filter in list views.
- Choose the Language of the value and enter the Value: the text users will see, up to 1,000 characters.
- If you are building a managed package, decide whether the label should be Protected (see below).
- Click Save.
Custom label naming rules
The Name follows Salesforce's usual API name rules. It must:
- contain only letters, numbers and underscores;
- begin with a letter;
- not contain spaces or two underscores in a row;
- not end with an underscore.
Pick a convention before you have dozens of labels, for example Area_Purpose such as Orders_Submitted_Message. It makes labels easy to find in Setup and in code reviews.
What does Protected mean?
The Protected setting matters only for managed packages. A protected label can be used by the package's own code but not referenced by the orgs that install the package, which lets the publisher change or remove it later without breaking subscribers. In an ordinary org it has no practical effect.
How do you translate custom labels?
Translations are what make labels worth using in multilingual orgs. To add one:
- Turn on Translation Workbench in Setup and add the languages you support. Users who will translate need translation permissions for those languages.
- Open the custom label and, in the Translations related list, click New.
- Select the language, enter the translated text and click Save.
Salesforce then shows each user the version for their own language. If no translation exists for a user's language, the label's own value is shown, so write the main value in your org's default language.
How do you use custom labels in code and Flow?
Every Salesforce UI technology can read custom labels; only the syntax differs. In the examples, the label's Name is Order_Submitted.
| Where | How to reference the label |
|---|---|
| Apex | System.Label.Order_Submitted |
| Lightning web component (JavaScript) | import orderSubmitted from '@salesforce/label/c.Order_Submitted'; |
| Aura component markup | {!$Label.c.Order_Submitted} |
| Aura component JavaScript | $A.get("$Label.c.Order_Submitted") |
| Visualforce | {!$Label.Order_Submitted} |
| Flow Builder | {!$Label.Order_Submitted}, or pick it from $Label in the resource picker |
Lightning web components
The LWC Developer Guide imports labels from the @salesforce/label module in the format namespace.labelName, where c is the default namespace (checked November 11, 2026). Import each label in the component's JavaScript, put the imported values in an object, and use that object in the template:
import { LightningElement } from 'lwc';
import orderSubmitted from '@salesforce/label/c.Order_Submitted';
export default class OrderStatus extends LightningElement {
label = { orderSubmitted };
}In the HTML template, show it with {label.orderSubmitted}. Salesforce resolves the user's language for you.
Apex
In Apex, System.Label.Order_Submitted returns the label in the running user's language. The Apex Label class also lets you read a label by name at run time, which helps when the label name comes from data. Because the reference is compiled, Salesforce stops you from deleting a label that Apex still uses.
Flow
Trailhead's global variables unit says you can place a custom label anywhere in Flow Builder that accepts a text resource, such as display text on a screen, a default value or a text formula (checked November 11, 2026). This keeps screen flow wording translatable too. If you are new to Flow, start with our Salesforce Flow guide.
How do you deploy custom labels between orgs?
Custom labels are metadata, so they move from a sandbox to production like any other configuration, not as records.
- Change sets: add the individual custom labels as components.
- Salesforce CLI and source control: in a source-format project, labels are stored in
labels/CustomLabels.labels-meta.xml. In apackage.xmlmanifest, name individual labels with theCustomLabeltype, or useCustomLabelswith a wildcard to retrieve them all. - Translations travel separately: the translated text is stored with each language's translation metadata, so include it in the deployment when you add or change translations.
Build and test labels in a sandbox first; our sandbox guide explains which sandbox type to use, and our Salesforce DevOps guide covers release pipelines.
Custom label limits to plan for
Two limits matter in practice. As of November 2026, Salesforce Help's Custom Labels page allows up to 5,000 custom labels per org, and the Apex Label class reference sets 1,000 characters as the maximum length of a label. Both figures also appeared in the 2021 version of this article.
Few orgs reach 5,000 labels, but large multi-team orgs with many components can. Delete labels no code uses, and avoid one label per sentence fragment: a label should hold a complete message so translators can work with whole sentences.
Common custom label mistakes
- Building sentences from fragments. Word order differs between languages; keep each message complete, and use placeholders that your code fills in.
- Hardcoding text "for now". Text inside Apex or JavaScript can't be translated; move it into a label before go-live.
- Vague short descriptions. "Message 1" helps no one; describe where the label appears.
- Forgetting translations in a release. A new label deploys with its main value only unless the translations are included.
- Using labels for configuration. Put IDs, thresholds and endpoints in custom metadata types, as our metadata guide explains.
Getting help
Techila is a Salesforce Summit Partner. Our Salesforce development services team builds multilingual Lightning web components, Apex and flows, and sets up translation and release processes that keep labels in step across orgs. Talk to a Salesforce architect about your org. We reply within 1 business day.
Frequently asked questions
What is a custom label in Salesforce?
A custom label is a named text value, such as an error message, button caption or help text, that you store once in Setup and reference from Apex, Visualforce, Lightning components and Flow. Because the text lives outside the code, you can reword it or translate it with Translation Workbench without changing or redeploying the code that uses it.
How many custom labels can you create in Salesforce?
Salesforce Help's Custom Labels page allows up to 5,000 custom labels per org, and the Apex Label class reference gives a maximum of 1,000 characters per label (both checked November 2026). If you are getting close to the limit, delete labels that no code or flow uses.
How do I use a custom label in a Lightning web component?
Import it from the @salesforce/label module, for example import orderSubmitted from '@salesforce/label/c.Order_Submitted', then expose it to the template through a property. The c prefix is the default namespace; a label from a managed package uses that package's namespace instead.
How do I translate custom labels?
Turn on Translation Workbench, add the languages you support, then open the label in Setup and use New in the Translations related list to enter the text for each language. Salesforce shows each user the translation for their language and falls back to the label's own value when no translation exists.
Can I use custom labels in Flow?
Yes. In Flow Builder the $Label global variable lists your org's custom labels, and Trailhead notes that you can place a label anywhere that accepts a text resource, such as screen component text, default values and text formulas. In a merge field it looks like {!$Label.Order_Submitted}.
What is the difference between custom labels and custom metadata types?
Custom labels hold user-facing text that may need translating. Custom metadata types hold configuration records, such as thresholds, mappings or endpoints, that your code and flows read at run time. Use labels for words people read and custom metadata types for settings that control behavior.