A dependent picklist is a picklist whose available values are filtered by the value of another field — called the controlling field. It’s a foundational data-quality pattern: pick “Country” first and the “State” dropdown only shows the relevant states. The controlling field can be a Picklist or a Checkbox; the dependent must be a Picklist or Multi-Select Picklist.
A familiar example
Country / State / City:
Country = "USA" → State picklist shows: AL, AK, AZ, AR, CA, CO, ...
Country = "Canada" → State picklist shows: AB, BC, MB, NB, NL, NS, ...
Country = "India" → State picklist shows: AP, AS, BR, CG, DL, ...Without dependency, users could pick Country = USA, State = Karnataka, producing meaningless data. The dependency makes nonsense combinations impossible at entry time.
Controlling and dependent — the contract
| Aspect | Controlling field | Dependent field |
|---|---|---|
| Type allowed | Picklist (single-select) or Checkbox | Picklist (single or multi-select) |
| Acts as | The “filter” — drives what’s visible | The “filtered” — shows different values per controller |
| Field-level security | Both fields must be visible to the user | — |
| Required | Independent of dependency configuration | — |
Notes:
- A Multi-Select Picklist can be a dependent but not a controlling field.
- A Checkbox as controller has only two states (true / false), so the dependent has at most two value sets.
How to configure
- Create both the controlling and the dependent picklists (with all their possible values).
- Open the dependent field’s settings.
- Click Field Dependencies → New.
- Select the controlling field.
- A matrix appears: rows are dependent values, columns are controlling values. Check the cells where the value should be available.
- Save.
After saving, the dependent picklist filters automatically on Lightning, Classic, mobile, and API.
Combinations and limits
- One controlling field per dependent. A single dependent picklist can only depend on one controlling field, not two.
- Cascading chains are allowed. A picklist can be dependent on field A and also be controlling for field B. So you can model Country → State → City as a 3-level chain (Country controls State; State controls City).
- Number of values: up to ~300 controlling values in the matrix (depending on edition). Beyond this you’ll need to split or restructure.
Where dependent picklists apply
| Context | Filter applied? |
|---|---|
| Lightning record edit | Yes |
| Classic record edit | Yes |
| Mobile app | Yes |
| Lookup-style picker | Yes |
| Quick Action with the field | Yes |
| Flow Screen Picklist component | Yes (Flow respects field dependencies) |
| SOAP / REST API insert / update | No — the API accepts any valid picklist value regardless of dependency |
| Apex assignment | No — Apex can set any value; you’d need to enforce via a validation rule for code paths |
This API-bypass behavior is important: dependent picklists prevent UI users from creating inconsistent data, but they do not prevent integrations from setting any value. For full enforcement, layer a validation rule that mirrors the dependency logic.
Limits to keep in mind
- Up to 7 levels of dependency cascading (Country → State → City → District → …). In practice 2-3 is what real orgs use.
- The controlling field cannot itself be a dependent of the field that depends on it (no cycles).
- Inactive picklist values can still be selected in some scenarios — be careful when deactivating values in a chain.
Dependent picklists vs Record Types
Record Types and dependent picklists overlap a bit — both filter picklist values for users. The difference:
- Record Types filter the entire set of values shown for a picklist, based on what kind of record (Sales Account vs Support Account) it is. The filter is fixed per record’s Record Type.
- Dependent picklists filter based on the value of another field on the same record, which the user can change at any time.
Use both together: Record Type narrows the overall menu; dependent picklists further filter dynamically.
A practical scenario
“On Case, you want the Sub_Type picklist to depend on the Type picklist.”
Case.Type values: Hardware, Software, Billing Case.Sub_Type values: Laptop, Desktop, Login, Password, Refund, Charge
Configure dependency matrix on Sub_Type, controlled by Type:
| Sub_Type | Hardware | Software | Billing |
|---|---|---|---|
| Laptop | ✓ | ||
| Desktop | ✓ | ||
| Login | ✓ | ||
| Password | ✓ | ||
| Refund | ✓ | ||
| Charge | ✓ |
Now when a user picks Type = Software, only Login and Password appear in Sub_Type.
Bottom line
Dependent picklists prevent invalid combinations at entry time by filtering one picklist based on another field’s value. They’re declarative, easy to configure, but enforced only in UI — pair with validation rules for API-side integrity.
Verified against: Salesforce Help — Define Dependent Picklists. Last reviewed 2026-05-17.