Controlling Field
A Controlling Field in Salesforce is a picklist or checkbox field whose value determines which values are available in a related Dependent Picklist on the same record.
Definition
A Controlling Field in Salesforce is a picklist or checkbox field whose value determines which values are available in a related Dependent Picklist on the same record. The pairing creates a dependent-picklist relationship: when the user picks a value in the Controlling Field, the Dependent Picklist refreshes to show only the values mapped to the chosen controlling value. The pattern reduces user error (the user cannot pick an invalid value combination) and shrinks long picklists into context-aware short ones.
A common example: Country as the Controlling Field and State or Province as the Dependent Picklist. The user picks United States, the State picklist shows US states. The user picks Canada, the State picklist shows Canadian provinces. Without the dependency, the State picklist would show every state and province in the world, and users could pick incompatible combinations. Controlling and Dependent fields are an essential data quality pattern for any object with multiple related picklists.
Why Controlling Fields are the cheap data quality win on any picklist-heavy object
Where Controlling Field dependencies live in setup
Object Manager, pick the object, Fields and Relationships, Field Dependencies. The page lists existing dependencies and lets admins create new ones. Each dependency has a Controlling Field, a Dependent Field, and a matrix of which Dependent values are available for each Controlling value. The matrix is the configuration; admins click cells to enable or disable Dependent values per Controlling value. The Controlling Field can be a picklist (standard or custom) or a checkbox; the Dependent Field must be a picklist (standard or custom).
The dependency matrix and the include-by-default question
When a dependency is first created, the matrix is empty by default; no Dependent values are available for any Controlling value. Admins click each cell (or use Include All to enable all combinations) to map dependencies. Most teams use Include All as a starting point and then disable specific cells to prevent invalid combinations, rather than starting empty and enabling cells one at a time. The matrix view supports keyboard navigation for fast editing of large picklists.
Multi-level dependencies and the cascading chain
A Dependent Picklist can itself be a Controlling Field for a deeper Dependent Picklist, producing a cascading chain. Country (controls) State (controls) City. The cascading pattern works but adds complexity; each level multiplies the matrix configuration. Most orgs cap at two levels because the matrix configuration burden grows fast. For deeper hierarchies, a custom Apex or Flow lookup is usually cleaner than chained picklists.
Behavior in the UI and the user experience
The dependent behavior renders automatically in Lightning record pages, Salesforce Mobile, and most LWC and Aura components that consume the field. The user picks a Controlling value; the Dependent field refreshes its picklist values without a page reload. If the user changes the Controlling value after picking a Dependent value, and the previously-picked Dependent value is no longer valid, the Dependent field clears and prompts re-selection. The behavior is consistent across the standard UI; custom components must handle the dependency through the metadata APIs explicitly.
Record Types and the dependency interaction
Record Types can restrict which picklist values are available per record type, independently of Field Dependencies. The two work together. A Country picklist with US, Canada, and Mexico might be restricted to US-only on a US Sales record type. Within US Sales, the State dependency still applies and shows only US states. The combination is powerful but adds configuration surface; admins must reason about both Record Type picklist restrictions and Field Dependency matrices when picking field values.
Data migration and the dependency enforcement
Field Dependencies enforce at the UI; bulk data import via Data Loader or the API can bypass them. A migration that loads Account records with Country = United States and State = Ontario succeeds at the API level even though the UI would prevent it. Most teams pair Field Dependencies with Validation Rules that enforce the same logic at the platform level so the dependency holds across all data entry paths. Without the validation rule, the dependency is a UI hint, not a data integrity guarantee.
Performance and the long-picklist limit
Field Dependencies have practical limits: the matrix can become unwieldy past a few hundred values per axis (Country x State for a global org with thousands of subdivisions). Salesforce supports up to around 1,000 values per picklist, but matrices that large slow the Lightning Render and create maintenance burden. For genuinely huge value sets, alternatives are: lookup relationship to a custom object, custom Apex picklist provider, or splitting the picklist into multiple grouped picklists by region.
How to set up a Controlling and Dependent Picklist pairing
The setup is straightforward but the maintenance is real. Pair with Validation Rules to enforce at the platform level, document the dependency matrix as part of object documentation, and audit when picklist values change.
- Confirm Controlling and Dependent fields exist as picklists
Both fields must exist before the dependency can be created. Create the picklists with their full value sets first.
- Open Field Dependencies for the object
Object Manager, pick the object, Fields and Relationships, Field Dependencies. Click New.
- Pick the Controlling Field and Dependent Field
Controlling is the field whose value drives the dependency. Dependent is the field whose available values change based on the Controlling value.
- Map the dependency matrix
Start with Include All to enable every combination, then disable specific invalid cells. The starting-empty pattern is slower for large picklists.
- Save and test in the UI
Open a record of the object, pick a Controlling value, confirm the Dependent picklist refreshes correctly. Test multiple Controlling values to verify the matrix.
- Add a Validation Rule for API-level enforcement
Field Dependencies enforce in the UI only. A Validation Rule that asserts the same logic at the platform level holds the dependency across Data Loader and API entry paths.
- Document the dependency in object documentation
The matrix is not self-explanatory to anyone who did not configure it. Document the rationale so future admins do not have to reverse-engineer.
Picklist or checkbox whose value drives the dependency.
Picklist whose available values change based on the Controlling value.
Per-cell configuration of which Dependent values are available for each Controlling value.
Platform-level enforcement that complements the UI-level dependency. Required for API-entry integrity.
Dependent fields can themselves control deeper Dependent fields. Adds matrix complexity per level.
- Field Dependencies enforce in the UI only. Data Loader and API can bypass them without a paired Validation Rule.
- The dependency matrix starts empty by default. Without Include All, no Dependent values appear; admins regularly miss this on first setup.
- Multi-level dependencies multiply matrix configuration burden. Cap at two levels unless absolutely required.
- Record Type picklist restrictions interact with Field Dependencies. Both apply simultaneously; reasoning about combined behavior takes practice.
- Picklists past a few hundred values per axis become unwieldy. Consider lookup relationships or grouped picklists for genuinely large value sets.
Trust & references
Cross-checked against the following references.
- Dependent Picklists referenceSalesforce
- Picklist fields overviewSalesforce
Straight from the source - Salesforce's reference material on Controlling Field.
- Define Field DependenciesSalesforce Help
- About Dependent PicklistsSalesforce Help
- Custom Field TypesSalesforce 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 is a Controlling Field?
Q2. What field types can serve as a Controlling Field?
Q3. What is a classic example of a controlling and dependent field pair?
Discussion
Loading discussion…