Field Dependency
A Field Dependency in Salesforce is a configuration that ties one picklist field's available values to the value currently selected in another field on the same record.
Definition
A Field Dependency in Salesforce is a configuration that ties one picklist field's available values to the value currently selected in another field on the same record. The first field is the controlling field, and the second is the dependent field. When a user picks a value in the controlling field, the dependent picklist filters down to only the values an admin marked as valid for that selection.
Field Dependencies are the declarative way to put if-then logic into picklist behavior. Without one, every value in the dependent picklist appears no matter what the controlling field says, and users can save combinations that make no sense. With one, the platform narrows the choices as the controlling value changes. The relationship is stored as field metadata and ships with the picklist fields, not as a separate validation rule.
How field dependencies filter picklist values
Controlling field versus dependent field
The relationship has a clear direction. The controlling field drives the options, and the dependent field reacts to it. A controlling field can be a standard or custom picklist, or a checkbox, as long as it lives on the same record. A dependent field has to be a picklist or a multi-select picklist. One controlling field can drive several dependent fields at once, which is handy when a single classification shapes many downstream choices. A dependent field, by contrast, answers to exactly one controlling field, so you cannot chain two controllers into the same dependent picklist. A checkbox controlling field gives you just two states, checked and unchecked, and you map dependent values to each. Picklist controlling fields give you one column per active value. Standard read-only system picklists usually cannot act as controllers, and lookup or master-detail relationship fields are never eligible. Picking the right controlling field early matters, because changing it later means rebuilding the dependency grid from scratch.
Configuring the dependency matrix
You set up the relationship in a grid that Salesforce calls the field dependency matrix. Controlling values run across the top as columns, and dependent values run down the side as rows. Each cell is a checkbox. When you include a dependent value under a controlling value, that value becomes available whenever the user selects that controlling option. You build the grid in Setup by opening Object Manager, choosing the object, opening the controlling field, and adding a new dependency that names the dependent field. From there you check the cells and save. You can double-click a single cell to toggle it, or click and drag to select a block of cells, then use Include Values or Exclude Values. A Preview button lets you test the result, and if record types are in play you can pick one to see how it narrows the choices alongside the controlling value. The grid is editable later, so the rules can grow as the business does.
Behavior on record forms
On a record page, the dependency works the moment a user touches the controlling field. Pick a controlling value and the dependent picklist immediately shows only the values mapped to it. Change the controlling value to something else and the dependent picklist refreshes again. If a dependent value was already chosen and it is no longer valid under the new controlling value, the platform clears it so the record cannot hold a stale combination. The controlling field has to be on the same page layout as the dependent field, otherwise the dependent picklist has nothing to react to and will not filter correctly. This is true on Lightning record pages and in older interfaces alike. Because the filtering happens in the browser as the user edits, it gives fast feedback and stops bad combinations before a save is ever attempted. The dependency does not change what the fields store, only which options the person sees while choosing.
Multi-select picklists as dependent fields
A multi-select picklist can serve as a dependent field, and it can also serve as a controlling field, though the controlling case is less common. As a dependent field, the multi-select shows the union of values allowed by the controlling selection, and the user can pick several of them. When a multi-select acts as the controlling field, the rule is stricter than people expect. A dependent value appears only when every controlling value that governs it is selected, not just one of them. That all-or-nothing logic catches teams off guard, so test it with real selections before rolling it out. As with single-select picklists, switching the controlling value can strip out dependent selections that no longer qualify, and the platform clears them without warning. Multi-select fields carry their own usability cost on top of this, so reach for them only when a record genuinely needs more than one value at the same time.
Field dependencies versus validation rules
Field dependencies and validation rules both guard data quality, but they act at different moments. A dependency works at the interface level while someone is editing, filtering the options so a bad pairing never shows up. A validation rule works at save time and inspects the values regardless of how they arrived. That difference matters because data can enter Salesforce without ever touching a page layout. An API call, an Apex insert, a data loader job, or an integration can all write a dependent value that the controlling value would forbid in the UI, because the dependency simply is not enforced on those paths. So a field dependency is a UX guardrail, not a hard integrity constraint. For rules the business truly cannot break, pair the two. Let the dependency keep the picklists clean for everyday users, and let a validation rule reject the same illegal combinations coming from automation and imports. Used together, they cover both the human and the programmatic doors into your data.
Limits and gotchas worth knowing
Field dependencies come with boundaries that shape your data model. A controlling picklist must have at least one and fewer than 300 values, and Salesforce Support can raise that ceiling to 500 on request. Some standard picklists are not allowed as controlling fields, so check before you design around one. You can set a default value on the controlling field, but not on a dependent picklist, and a default left on a dependent field can show even when the controlling value should hide it. Setting up a dependency on a field that already holds data does not clean the existing records, so older rows can keep combinations the new rule would block until you fix them with a separate data pass. Record types add another layer, because a dependent value shows only when it is allowed by both the record type and the controlling value. Reports and list views ignore dependencies entirely, listing every dependent value in their filters no matter what the controlling filter says.
How to create a field dependency
You create a field dependency from the controlling picklist in Object Manager, then map valid dependent values in the dependency matrix. Both fields must already exist on the same object before you start.
- Open the controlling field
In Setup, go to Object Manager, pick the object, open Fields and Relationships, and click the picklist or checkbox you want as the controlling field. Both the controlling and dependent fields must exist first.
- Add a new dependency
On the field detail page, find the Field Dependencies related list and click New. Choose the controlling field and the dependent field for this relationship, then continue to the matrix.
- Map values in the matrix
Columns are controlling values and rows are dependent values. Double-click cells, or click and drag a block, then use Include Values to mark which dependent options are valid under each controlling value.
- Preview and save
Click Preview to test the filtering, and pick a record type if you use them to confirm the combined result. When the grid looks right, click Save to store the dependency as field metadata.
- Confirm the layout
Make sure both the controlling and dependent fields sit on the same page layout. If the controlling field is missing from the layout, the dependent picklist has nothing to react to and will not filter.
A standard or custom picklist (at least one and fewer than 300 values) or a checkbox on the same record. It drives which dependent values appear.
A picklist or multi-select picklist on the same object. Its available values are filtered by the controlling selection. It can answer to only one controlling field.
The grid where you check which dependent values are valid under each controlling value, with Include Values, Exclude Values, and Preview controls.
An optional preview setting. When record types are used, a dependent value shows only when both the record type and the controlling value allow it.
- The controlling field must be on the same page layout as the dependent field, or the dependent picklist will not filter.
- Adding a dependency does not clean existing records; older rows can keep combinations the new rule would block until you fix them.
- Field dependencies are not enforced for API, Apex, or data-loader writes. Add a validation rule to catch illegal combinations from automation.
- A default value on a dependent picklist can appear even when the controlling value should hide it, so avoid dependent defaults.
Prefer this walkthrough as its own page? How to Field Dependency in Salesforce, step by step
Trust & references
Cross-checked against the following references.
- Dependent PicklistsSalesforce
- Dependent Picklist ConsiderationsSalesforce
Straight from the source - Salesforce's reference material on Field Dependency.
- Define a Dependent PicklistSalesforce
- Dependent Picklists Screen Input ComponentSalesforce
Hands-on resources to go deeper on Field Dependency.
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. In a Field Dependency, what is the relationship between the controlling field and the dependent field?
Q2. Which pairing of field types is valid for a Field Dependency configuration?
Q3. What happens to a previously selected dependent value when the user changes the controlling field to one that no longer permits it?
Discussion
Loading discussion…