Dependent Fields
Provides a mechanism to create dependent entity reference fields where child field options are dynamically filtered based on the selection of a parent field using Views.
dependent_fields
Install
composer require 'drupal/dependent_fields:^1.0'
Overview
Dependent Fields module allows site builders to create cascading entity reference fields where the available options in a child field are dynamically updated based on the selected value in a parent field. This creates conditional field relationships that enhance form usability and data integrity.
The module provides a custom Entity Reference Selection plugin that uses Views with Entity Reference displays to filter available options. When a user selects a value in the parent field, an AJAX request retrieves the filtered options for the dependent child field without reloading the entire page.
This is particularly useful for scenarios like selecting a country first and then showing only cities from that country, or selecting a category and showing related subcategories. The module supports multi-value fields, paragraphs, and can reference parent fields by UUID for configuration portability between sites.
Features
- Creates cascading/dependent entity reference fields where child field options are filtered based on parent field selection
- Uses Views with Entity Reference display to define filterable option sets with powerful query capabilities
- Real-time AJAX-based field option updates without page reload when parent field changes
- Supports multiple parent field values (allows multiple values in contextual filter)
- Works with Select list, Checkboxes, and Radio buttons widgets
- Support for multi-value (unlimited cardinality) dependent fields
- Full support for Paragraphs - dependent fields work correctly within nested paragraph structures
- UUID-based parent field referencing for configuration portability between environments
- Supports Tagify widget for entity autocomplete fields
- Preserves current selection state when dependent field options are updated
- Automatic change event dispatching when options are updated to trigger subsequent dependent field updates
Use Cases
Country and City Selection
Create a two-field setup where users first select a country from a taxonomy vocabulary, and then the city field automatically filters to show only cities associated with that country. Configure a View that lists city terms with a contextual filter on the parent country reference field.
Product Category and Subcategory
Implement a hierarchical product categorization where selecting a main category filters the subcategory options. Use a View with taxonomy term relationships to filter child terms based on parent selection.
Department and Employee Selection
Allow users to first select a department, then show only employees that belong to that department. Create a View of user entities filtered by a department reference field, using the department selection as the contextual filter.
Multi-level Dependent Fields
Chain multiple dependent fields together. For example: Region → Country → City. Each field's selection filters the next field's options. The module dispatches change events after updates, triggering subsequent dependent field updates.
Paragraphs with Dependent Fields
Use dependent fields within Paragraph types for complex content structures. The module correctly handles nested paragraph contexts and can find parent field values within the same paragraph or parent paragraph.
Configuration Sync Between Environments
When deploying configuration between development, staging, and production environments, enable 'Reference parent by UUID' option to ensure the View contextual filter receives entity UUIDs instead of IDs, which may differ between environments.
Tips
- Always test your View independently before configuring it as a dependent field source - ensure it returns correct results with the expected contextual filter values
- For multi-value parent fields, enable 'Allow multiple values' in the View's contextual filter settings so it can accept comma-separated IDs
- The parent field value is always passed as the first argument to the View, followed by any additional arguments specified in the configuration
- Use the 'arguments' field to pass additional static contextual filters to the View beyond the parent field value
- For better performance with large option sets, consider adding appropriate caching to your Views
Technical Details
Hooks 1
hook_field_widget_single_element_form_alter
Alters entity reference field widgets to add AJAX behavior for parent fields. When a field is identified as a parent of one or more dependent fields, this hook adds AJAX handlers that trigger updates to the child fields when the parent value changes.
Troubleshooting 5
Ensure the dependent field is using 'Select list' or 'Check boxes/radio buttons' widget in Manage Form Display. Autocomplete widgets are not supported for dependent fields.
Make sure the View has an Entity Reference display type. Only Views with Entity Reference displays are eligible for use with dependent fields.
Verify that the View's contextual filter is correctly configured to accept the parent field value. Check that the View returns results when manually testing with the expected argument values.
The module supports Paragraphs, but ensure both parent and child fields are within the same paragraph or that the parent field is accessible from the paragraph context.
Enable 'Reference parent by UUID instead of entity ID' option in the field settings to ensure configuration portability when entity IDs differ between environments.