Dependent Field
A Dependent Field in Salesforce is a picklist field whose available values are constrained by the current value of a related Controlling Field.
Definition
A Dependent Field in Salesforce is a picklist field whose available values are constrained by the current value of a related Controlling Field. The pairing (Controlling Field + Dependent Field) creates a dependent-picklist relationship: when the user picks a value in the Controlling Field, the Dependent Field refreshes to show only the values that are valid for that controlling choice. The classic example is Country as the Controlling Field and State or Province as the Dependent Field; picking United States constrains the State picklist to US states, picking Canada constrains it to Canadian provinces.
Dependent Fields exist because some picklists only make sense in the context of another picklist. Without the dependency, the platform would show every State or Province in the world regardless of country, letting users pick invalid combinations and degrading data quality. The Dependent Field is the constrained side of the relationship; the matrix of which dependent values are available per controlling value is configured through Field Dependencies in Object Manager. The pattern is essential for any object with multiple related picklists.
Why Dependent Fields are the data-quality pattern for related picklists
Where Dependent Fields live and how they relate to Controlling Fields
Object Manager, pick the object, Fields and Relationships shows every field. The Dependent Field is configured through Field Dependencies (in the same object's Fields and Relationships sub-menu) where the admin picks a Controlling Field and a Dependent Field, then configures the matrix of valid combinations. The Dependent Field must be a picklist or multi-select picklist; the Controlling Field can be a picklist or checkbox. Both fields exist as independent fields first; the dependency is the relationship layer between them.
The dependency matrix and the include-default question
The matrix is the configuration. Each cell represents a (Controlling value, Dependent value) pair; clicking the cell toggles whether that pair is allowed. Salesforce defaults to no cells enabled (a fresh dependency hides every Dependent value for every Controlling value). Admins use Include All to enable every combination as a starting point and then disable invalid cells, rather than enabling cells one at a time. The Include All starting pattern is dramatically faster for large picklists.
Runtime behavior in the UI
When a user opens a record edit page, the Dependent Field shows values per the current Controlling Field value. Changing the Controlling Field refreshes the Dependent Field without a page reload; the Dependent value resets if the previous value is no longer valid. The behavior is consistent in Lightning record pages, Salesforce Mobile, and standard LWC and Aura components. Custom components must handle the dependency through the metadata APIs explicitly; not every custom component honors the dependency.
Multi-level dependencies and the cascading pattern
A Dependent Field can itself be a Controlling Field for a deeper Dependent Field: Country controls State, State controls City. The cascading pattern works but adds complexity; each level multiplies the matrix configuration. Most orgs cap at two levels because deeper hierarchies become impractical to maintain. For genuine three-or-more-level hierarchies, lookup relationships to a custom Geography object are usually cleaner than chained picklists.
Field Dependencies vs Record Types and the layered behavior
Record Types can restrict picklist values per record type independently of Field Dependencies. The two layer together: a Country picklist restricted to US-only on the US Sales record type, combined with State Field Dependency that constrains by Country, produces a State picklist showing US states only when the record is on the US Sales record type. Reasoning about combined Record Type plus Field Dependency picklist behavior takes practice; document the intent so future admins do not have to reverse-engineer.
Data migration and the API-level bypass
Field Dependencies enforce in the Salesforce UI; the API (Data Loader, Bulk API, SOAP, REST) does not enforce them. A migration that loads records with Country = United States and State = Ontario succeeds at the API level. The mitigation: pair Field Dependencies with Validation Rules that express the same constraint as a Validation Rule formula. The Validation Rule enforces at the platform level across both UI and API. Without the validation rule, the Dependent Field is a UI hint, not a data integrity guarantee.
Performance and the picklist-size practical limits
Field Dependencies are fast at typical picklist sizes (under a hundred values per axis). At very large picklist sizes (Country with 250 countries and Subdivision with thousands), the matrix becomes unwieldy and the runtime picklist refresh slows. For very large value sets, alternatives include: lookup relationship to a custom object with reference data, custom Apex picklist provider, or splitting the picklist into multiple grouped picklists by region.
How to set up a Dependent Field properly
The pattern: confirm both Controlling and Dependent fields exist as picklists, create the dependency, map the matrix with Include All as starting point, pair with Validation Rule for API-level enforcement. The setup is straightforward; the discipline is in the validation rule pairing.
- Create the Controlling and Dependent picklists first
Both fields must exist before the dependency can be created. Build the picklists with their full value sets.
- Open Field Dependencies for the object
Object Manager, pick the object, Fields and Relationships, Field Dependencies. Click New.
- Pick Controlling and Dependent fields
Controlling is the field whose value drives the dependency. Dependent is the field whose available values change based on Controlling.
- Use Include All to start the matrix
Enable every combination as the starting point. Then disable invalid cells. Faster than enabling cells one at a time for large picklists.
- Save and test in the UI
Open a record, pick a Controlling value, confirm the Dependent picklist refreshes correctly. Test multiple Controlling values.
- Add a Validation Rule for API enforcement
Field Dependencies enforce only in the UI. A Validation Rule that asserts the same constraint at the platform level holds the dependency across Data Loader and API.
- Document the dependency rationale
The matrix is not self-explanatory. Document the intent in object documentation so future admins understand why specific combinations are disabled.
Picklist or checkbox whose value drives the Dependent Field's available values.
Picklist whose available values are constrained by the Controlling Field.
Per-cell configuration of which (Controlling, Dependent) pairs are valid.
Platform-level enforcement complementing 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 bypass them; pair with a Validation Rule for full integrity.
- The 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 genuinely required.
- Record Type restrictions and Field Dependencies layer together. Reason about combined behavior carefully; document the intent.
- Very large picklists make the matrix unwieldy. Consider lookup relationships for value sets past a few hundred per axis.
Trust & references
Cross-checked against the following references.
- Dependent Picklists referenceSalesforce
- Picklist fields referenceSalesforce
Straight from the source - Salesforce's reference material on Dependent Field.
- About Dependent PicklistsSalesforce Help
- Define Field DependenciesSalesforce Help
- Picklist FieldsSalesforce 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 Dependent Field?
Q2. What's a classic example of a controlling and dependent field pair?
Q3. Why use dependent fields?
Discussion
Loading discussion…