List Custom Settings
List Custom Settings are a type of Salesforce Custom Setting that store key-value pairs accessible from Apex without consuming SOQL query limits.
Definition
List Custom Settings are a type of Salesforce Custom Setting that store key-value pairs accessible from Apex without consuming SOQL query limits. Each record is identified by a Name field; code retrieves records by name through the generated getValues(name) or getAll() methods. List Custom Settings differ from Hierarchy Custom Settings by the absence of per-user or per-profile precedence: every record is the same to every user, identified by name only. They are the right tool for configuration data that does not vary per user but does need to be cached for performance.
Common uses include environment-specific configuration (API endpoints that change between sandbox and production), application reference data (currency rates, country codes), and feature toggles that apply to everyone (a kill switch for a feature being beta tested). List Custom Settings cap at 10 MB total across all settings in the org and have field-type restrictions, so they are not a replacement for full custom objects. They occupy a specific niche: cached configuration small enough to fit the cap.
When and how to use List Custom Settings
List versus Hierarchy
List has no precedence model; every record is independent. Hierarchy has the per-user-per-profile-per-org cascade. Choose List for configuration that applies to all users equally; choose Hierarchy when configuration legitimately varies per user. The two cannot be converted; the choice is fundamental at setting creation.
Access patterns from Apex
getValues(name) returns a single record. getAll() returns all records as a Map keyed by Name. Both are cached; reads do not count against SOQL limits. The methods are generated on the Custom Setting sObject class. Most code uses one or the other depending on whether it needs one specific record or to iterate.
Caching and update propagation
Custom Settings cache in memory at the application server level. Reads are fast and limit-free. Updates take a few seconds to propagate across all servers, so code that updates and immediately reads may see stale values briefly. For most use cases this is invisible; for synchronous transaction-critical updates, plan accordingly.
Field types and 10 MB cap
Supported field types include Text up to 300 characters, Number, Email, Checkbox, Phone, URL, and a few others. Long text areas, lookups, formulas, and rich text are not supported. The org-wide cap is 10 MB total across all Custom Settings (List and Hierarchy combined). Hit this cap and the platform blocks new records. Plan size carefully.
Deployment data challenge
Custom Setting schema deploys through changesets. Custom Setting data does not. Moving records from sandbox to production requires manual recreation or Apex/Data Loader population scripts. For environment-specific values, this is intentional (you would not deploy sandbox endpoints to production). For shared reference data, it is friction.
Custom Metadata Types as the modern alternative
Custom Metadata Types (CMDT) were introduced to address the deployment data challenge: CMDT records deploy as metadata, moving with code through changesets and SFDX. For shared reference data and configuration that should travel with releases, CMDT is the better tool. List Custom Settings remain useful for environment-specific data and large data sets that exceed CMDT's record-count limits.
When to use a custom object instead
If the configuration needs validation rules, triggers, sharing rules, or unsupported field types, use a regular custom object instead. List Custom Settings are intentionally simple; complex configuration belongs in a proper sObject with the full feature set.
Create and access a List Custom Setting
Creating a List Custom Setting involves schema definition, data population, and Apex access. The steps below cover the full setup.
- Decide List versus Hierarchy versus CMDT
List for per-record-identified-by-name configuration. Hierarchy for per-user variance. CMDT for shared reference data that should deploy with releases.
- Create the Custom Setting
Setup > Custom Settings > New. Name it, set Type to List, choose Public or Protected visibility. Save.
- Add fields
From the detail page, add fields for the values you need (Text, Number, Email, Checkbox). Field types are limited; complex types require a custom object instead.
- Populate records
Manage > New. Add records with Name and field values. For bulk, use Data Loader.
- Access from Apex
Call MySetting__c.getValues('SomeName') for one record. Call MySetting__c.getAll() for the full map keyed by Name.
- Plan deployment
Schema deploys through changesets. Data does not. Write a post-deployment Apex script or Data Loader job to populate each target environment.
- Document the setting
Add field-level help text and a comment in the Apex code referencing the setting. Future developers will need to understand the purpose.
Primary identifier for each record. Use a meaningful naming convention.
Text, Number, Email, Checkbox, Phone, URL, etc. Limited compared to custom objects.
Accessible from any Apex code. The standard choice.
Accessible only within the same namespace. For managed packages.
One record by name versus all records as a Map.
- Data does not deploy through changesets. Plan recreation or population in each environment.
- 10 MB cap across all Custom Settings. Hitting it blocks new records.
- Update propagation takes a few seconds. Immediate reads may see stale values.
- Field types are limited. For complex configuration, use a custom object instead.
- Custom Metadata Types are the modern alternative for deployable configuration. Reach for them first.
Trust & references
Straight from the source - Salesforce's reference material on List Custom Settings.
- Create Custom SettingsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What are List Custom Settings?
Q2. How do List Custom Settings differ from Hierarchy Custom Settings?
Q3. What's a typical use case?
Discussion
Loading discussion…