A field dependency in Salesforce controls which values are available in one field, called the dependent field, based on the value selected in another field, called the controlling field. It is a filter, not an automation rule.
That distinction matters. Field dependencies are frequently confused with validation rules and flows, which do very different jobs. Field dependencies do exactly one thing: they narrow the options in a picklist so users only see choices that make sense for what they already selected.
This guide covers what field dependencies in Salesforce are, how controlling and dependent fields differ, which data types are allowed in each role, and how to create a field dependency step by step.
What Is a Field Dependency in Salesforce?
A field dependency in Salesforce is a filter that changes the values available in a dependent picklist based on the value selected in a controlling field. Salesforce reads the controlling field first, then shows only the dependent values you mapped to that selection.
The classic example is geography. If Country is the controlling field and State is the dependent field, selecting "United States" limits the State picklist to US states rather than showing every state and province worldwide.
Both fields must live on the same object and apply to the same record. A field dependency cannot reach across objects.
Field dependencies also do not enforce anything after the fact. They filter what a user can pick in the interface. They do not validate imported data, and they do not populate values automatically.
Controlling Field vs. Dependent Field: What's the Difference?
The controlling field determines which options are available. The dependent field is the one whose options get narrowed.
The two roles follow different data type rules. A controlling field can be a standard picklist, a custom picklist, or a checkbox. A dependent field must be a custom picklist or a custom multi-select picklist.
A controlling picklist needs at least one value, and Salesforce documents a ceiling of 300 values for controlling fields. If a field acts as both a controlling field and a dependent picklist in a chain, that same 300-value ceiling applies.
One controlling field can filter several dependent picklists. A dependent picklist, on the other hand, can have only one controlling field.
Can a Text Field Be a Dependent Field in Salesforce?
No. A text field cannot be a dependent field in Salesforce. Dependent fields must be custom picklists or custom multi-select picklists.
The same restriction rules out number fields, date fields, formula fields, lookup fields, and standard picklists. Standard picklists can serve as controlling fields, but Salesforce does not allow them in the dependent role.
If you need a text field to change based on another field value, a field dependency is the wrong tool. Use a formula field for a calculated value, or a flow when you need to write a value to the record.
How to Create a Field Dependency in Salesforce (Step-by-Step)
You need the "Customize Application" permission to define or edit dependent picklists. Confirm both fields already exist and have their values populated, because Salesforce will not build a dependency on an empty picklist.
- From Setup, click Object Manager and select the object that holds both fields.
- Click Fields & Relationships, then click the Field Dependencies button.
- Click New.
- Select the controlling field from the Controlling Field dropdown.
- Select the dependent field from the Dependent Field dropdown, then click Continue.
- In the field dependency matrix, the top row lists the controlling field values and the columns list the dependent field values. Select the dependent values that should be available for a given controlling value, then click Include Values.
- Repeat for each controlling value. Scroll horizontally if the matrix is wider than your screen.
- Click Preview to test the behavior. If your org uses record types, select a record type in the preview to see how it changes the available values.
- Click Save.
Exclusion works exactly as the name suggests. If a dependent value is not included for a controlling value, users do not see that option when the controlling value is selected.
Common Use Cases for Field Dependencies
Field dependencies earn their keep anywhere a long picklist has an obvious parent category. Three patterns cover most enterprise orgs.
Country to State or Province
Selecting a country narrows the state or province list to that country. Worth knowing before you build: Salesforce ships State and Country/Territory Picklists as a standard platform feature that already handles this for standard address fields. Build a custom dependency only when you need coverage the standard picklists do not provide.
Product Line to Product
A Product Line picklist controls a Product picklist so a rep who selects "Enterprise Platform" sees only the SKUs in that line. This keeps quoting accurate and keeps pipeline reports clean, because reps cannot pair a product with the wrong line.
Industry to Sub-Industry
An Industry picklist controls a Sub-Industry picklist, so selecting "Financial Services" surfaces options like Banking, Insurance, and Capital Markets. Segmentation stays consistent, which matters when marketing and sales report off the same field.
Field Dependency Limits and Gotchas
Most field dependency problems trace back to a handful of documented behaviors rather than a misconfigured matrix.
- Both fields must be on the layout. A dependent picklist only shows filtered values when its controlling field is on the same page layout, and the dependent field should sit below the controlling field. The same rule applies to Lightning pages that use Dynamic Forms.
- Field-level security is independent. Hiding a dependent picklist does not hide its controlling field. Hide both together or the filtering silently stops making sense.
- Imports bypass the dependency. The Data Import Wizard does not honor field dependencies. Any value can land in a dependent picklist regardless of what the controlling field holds.
- Replacing a controlling value breaks the dependency. If you replace a value in the controlling picklist, the dependency is lost and has to be rebuilt against the new value. Changing picklist value API names after setup breaks the mapping too, because dependencies are stored against API names.
- Record types add a second filter. The record type determines which controlling values appear. The record type and the selected controlling value together determine which dependent values appear.
- A required dependent picklist can still save empty. If no dependent values are available for the selected controlling value, users can save the record with that field blank.
- Converting existing fields is safe for existing data. Turning existing fields into a controlling and dependent pair does not change values already stored on records. The rules apply to new records and to future edits.
Best Practices for Setting Up Field Dependencies
Keep picklist value counts manageable. A controlling picklist that approaches the 300-value ceiling produces a matrix that is close to unmaintainable by hand, and the admin who inherits it pays that cost every release.
Confirm the "Customize Application" permission before you start, and confirm the values in both picklists are final. Values added later are excluded by default, so every addition means a return trip to the matrix.
Build and test in a sandbox before deploying to production. Field dependencies are metadata, so they travel between orgs like any other configuration change, and a dependency that arrives half-mapped is easy to miss in a large release. Teams moving them with change sets should know the documented limits of that approach.
Document the mapping outside the matrix. Setup is the only place the logic lives, and Salesforce does not offer a report of controlling and dependent field pairs, so a simple spreadsheet saves the next admin hours.
Preview against every record type before you save. A mapping that looks complete under one record type can leave another record type with no available values at all.
Putting Field Dependencies to Work in Your Org
Field dependencies come down to one relationship: a controlling field narrows the values available in a dependent picklist. Get the data types right (standard picklist, custom picklist, or checkbox in the controlling role; custom picklist or custom multi-select picklist in the dependent role) and the rest is mapping.
The harder part is what happens after Setup. Dependencies built in a sandbox have to reach production intact, survive future releases, and stay documented as picklist values change. That is a release management problem rather than a configuration problem.
Flosum helps enterprise Salesforce teams deploy and govern declarative changes like field dependencies with full visibility into what moved, when, and who approved it. See how it works on the Flosum DevOps platform, or request a demo.
Frequently Asked Questions (FAQ)
Thank you for subscribing
