How to Use Custom Labels in Salesforce

Custom labels in Salesforce are custom text values — each up to 1,000 characters — that you define once and reference from Apex, Visualforce, Lightning (Aura and LWC), and Flow, then translate through the Translation Workbench so a single org can serve users in their native language without hardcoded strings. An org can hold up to 5,000 custom labels.

Because the text lives in metadata rather than in code, you can change wording or add a new language without editing and redeploying a single class or component — which is exactly why custom labels are the recommended home for every user-facing string.

Key takeaways

• What they are: reusable, translatable text values referenced from Apex, Visualforce, Aura, LWC, and Flow.
• Limits: up to 5,000 labels per org; each value up to 1,000 characters. Labels inside installed managed packages do not count toward your limit.
• Where to create them: Setup → quick-find Custom Labels → New Custom Label (Name, Value, Categories).
• Translation: activate the language in Translation Workbench, then add a translation per label.
• Reference syntax differs per context — Apex uses System.Label.MyLabel, LWC uses an @salesforce/label import. See the table below.
• Not the same as config storage: use custom settings or custom metadata types for app configuration and mappings, not for UI text.

What are custom labels in Salesforce?

A custom label is a named, single text value stored as metadata. You give it an API Name (used in code), a default Value (the text shown), an optional Description, and optional Categories used to organize and filter labels in list views.

Two properties make labels powerful:

1. Centralization. The same string can be referenced from many places. Change the label value once and every Apex class, page, and component that references it updates — no redeployment required.
2. Translation. Pair a label with the Translation Workbench and Salesforce automatically returns the value in each user's language, based on their Language personal setting. This is the foundation for building a multilingual application.

How do you create a custom label?

1. From Setup, enter Custom Labels in Quick Find and select it. (In older Setup menus this lived under Build → Create → Custom Labels.)
2. Click New Custom Label.
3. Fill in the fields:
   • Short Description — a human-readable label name shown in the UI.
   • Name — the unique API name used in code (letters, numbers, and underscores; must start with a letter).
   • Protected Component — check this if the label ships in a managed package and you want to stop subscribers from referencing it.
   • Categories — comma-separated terms used as filter criteria in custom-label list views (organization only; not shown to end users).
   • Value — the default text, up to 1,000 characters. This is what is returned when no translation applies.
4. Click Save.

How do you add translations to a custom label?

Translations turn one label into a multilingual string:

1. First enable the Translation Workbench and activate the languages you need: Setup → Translation Language Settings → add and activate each language.
2. Open the custom label you created (Setup → Custom Labels → click the label name).
3. In the Translations related list, click New.
4. Choose a Language (only activated languages without an existing translation appear) and enter the translated Translation Text.
5. Click Save.

At runtime Salesforce returns the translation that matches the running user's language; if none exists for that language, it falls back to the label's default Value.

How do you reference a custom label in code?

The label is the same everywhere, but the reference syntax depends on the context. c is the default namespace — use your own package namespace instead when the label is namespaced.

Context	Syntax
Apex	System.Label.MyLabel (shorthand Label.MyLabel)
Visualforce	{!$Label.c.MyLabel}
Aura component	{!$Label.c.MyLabel}
Lightning Web Component	import myLabel from '@salesforce/label/c.MyLabel';
Flow	{!$Label.c.MyLabel} (the $Label global)

In Apex you cannot reference a label dynamically by string name through System.Label; for that, query the translation/ExternalString objects or use the System.Label.get patterns available in newer API versions.

// Apex — reference a custom label directly
String greeting = System.Label.Welcome_Message;
System.debug(greeting); // returns the value in the running user's language

// Visualforce
// <apex:outputText value="{!$Label.c.Welcome_Message}" />

// Aura component
// <aura:component>
//   {!$Label.c.Welcome_Message}
// </aura:component>

// Lightning Web Component — labelExample.js
import { LightningElement } from 'lwc';
import welcomeMessage from '@salesforce/label/c.Welcome_Message';

export default class LabelExample extends LightningElement {
    // Expose imported labels to the template via an object
    label = {
        welcomeMessage,
    };
}

<!-- Lightning Web Component — labelExample.html -->
<template>
    <p>{label.welcomeMessage}</p>
</template>

Custom labels vs custom settings vs custom metadata types

A frequent point of confusion: all three store values outside of code, but they solve different problems. Use custom labels for text shown to users, and the other two for configuration and data.

Aspect	Custom Labels	Custom Settings	Custom Metadata Types
Best for	User-facing strings, error/help text, i18n	Org-, profile-, or user-specific config values	Structured app configuration, mappings, rules
Data shape	One text value per label (+ translations)	Field-based records (List or Hierarchy)	Field-based records ("rows")
Translatable via Translation Workbench	Yes	No	Labels translatable; record values limited
Records deploy with metadata	Definitions deploy	Definition deploys, data does not	Definition and records deploy
Apex access	System.Label.X	MySetting__c.getInstance()	MyType__mdt.getAll() / SOQL
Counts against SOQL limits	No	No	No (queries are cached)
Scale	5,000 labels, 1,000 chars each	Limited by data storage	Limited by metadata size

Rule of thumb: if a string is shown to a person and might need translating, it belongs in a custom label. If a value controls how your app behaves, reach for a custom setting (mutable, per-user/profile) or a custom metadata type (deployable, packageable).

What are the limits and best practices?

Limits

• Up to 5,000 custom labels per org.
• Each label Value (and each translation) can be up to 1,000 characters.
• Custom labels delivered inside an installed managed package do not count toward your org's 5,000 limit.

Best practices

• Externalize every user-facing string. Button text, toast messages, validation errors, and help text should all come from labels, never hardcoded — this is what makes a multilingual rollout a configuration change instead of a code change.
• Use Categories to group related labels (for example Onboarding, Errors) so they are easy to filter and maintain in list views.
• Adopt a naming convention such as Feature_Purpose (Cart_Empty_Message) so labels are self-documenting in code.
• Plan translations early. Activate languages in the Translation Workbench and supply translations for each label rather than retrofitting i18n later.
• Reference with the namespace (c. or your package namespace) in Visualforce, Aura, LWC, and Flow for portability across orgs.

For more on structuring an org so it stays maintainable as it grows, see our guide to Salesforce customization best practices, and our walkthrough of Salesforce permission sets for controlling who can see and edit translated content.

Frequently Asked Questions

What is a custom label in Salesforce?

A custom label is a named text value, up to 1,000 characters, stored as metadata. You reference it from Apex, Visualforce, Aura, LWC, and Flow instead of hardcoding strings, and you can translate it per language through the Translation Workbench.

How many custom labels can an org have?

An org can have up to 5,000 custom labels, and each label value can be up to 1,000 characters. Labels that arrive inside an installed managed package do not count toward the 5,000 limit.

How do I reference a custom label in a Lightning Web Component?

Import it from the @salesforce/label scoped module — for example import welcome from '@salesforce/label/c.Welcome_Message'; — then expose it to your template through a property or getter so you can use it as {label.welcome} in HTML.

How do custom labels support multiple languages?

Activate the target languages in the Translation Workbench, then add a translation for each label. At runtime Salesforce returns the translation that matches the running user's Language setting, falling back to the label's default value when no translation exists.

What is the difference between custom labels and custom metadata types?

Custom labels store translatable, user-facing text and are read with System.Label. Custom metadata types store structured configuration records that deploy with your metadata and are read with getAll()/getInstance() or SOQL. Use labels for UI text and metadata types for app configuration.

Can I change a custom label without redeploying code?

Yes. Because the value lives in metadata, editing a label's value or adding a translation updates every reference instantly, with no need to modify or redeploy the Apex classes, pages, or components that use it.

Need a hand building a multilingual or heavily customized Salesforce org? Our team offers Salesforce development and customization services — from Translation Workbench rollouts to Apex and LWC builds — so your platform scales cleanly across regions and teams.