Conditional Fields
Allows you to manage sets of dependencies between fields, making dependent fields visible, required, or have other states based on the values of control fields.
conditional_fields
Overview
Conditional Fields is a powerful module that allows you to define dependencies between fields on any entity type that supports the Field API (nodes, users, taxonomy terms, media, paragraphs, etc.). When a field is marked as "dependent", it will only be available for editing and/or displayed based on the state of a "control" (dependee) field matching specified conditions.
The module leverages Drupal's States API to dynamically modify dependent fields on the client side when editing entities. For example, you can create a custom "Article teaser" field that only appears when a "Has teaser" checkbox is checked. The module supports complex dependency configurations including multiple conditions combined with AND, OR, or XOR logic.
Conditional Fields provides a flexible plugin system for handling different field widget types, allowing for accurate state evaluation across various field types including text fields, select lists, checkboxes, radios, date fields, entity references, and more. It also supports visual effects like fade and slide animations when fields change visibility.
Features
- Define field dependencies based on control field values, states (filled/empty, checked/unchecked, touched/untouched, focused/unfocused)
- Support for multiple target states: visible/invisible, enabled/disabled, required/optional, collapsed/expanded, checked/unchecked, filled/emptied
- Client-side dynamic field behavior using Drupal's States API
- Multiple value matching modes: exact widget value, regular expression, AND (all values), OR (any value), XOR (exactly one value), NOT (none of the values)
- Visual effects for visibility changes: instant show/hide, fade in/out, slide up/down with configurable speed
- Support for all major entity types: nodes, media, block content, comments, users, taxonomy terms, and paragraphs
- Integration with contributed modules like Inline Entity Form, Paragraphs, and Field Group
- Inheritance system allowing conditions to propagate to child fields within container fields
- Configurable dependency grouping (AND, OR, XOR) when multiple dependencies exist on a single field
- Custom jQuery selector support for advanced use cases
- Reset dependent field to default values when dependency is not triggered
- Plugin system for extending field handler support to custom field types
- Convenient admin interface with tabs on entity type configuration pages
Use Cases
Show additional fields based on content type selection
Create a 'Content Type' select field with options like 'Article', 'Event', 'Product'. Configure conditional fields to show event-specific fields (Date, Location, Registration Link) only when 'Event' is selected, and product-specific fields (Price, SKU, Inventory) only when 'Product' is selected.
Required fields based on publication status
Make certain fields required only when content is being published. For example, make the 'Featured Image' field required only when the 'Promote to front page' checkbox is checked, ensuring published content always has proper imagery.
Progressive disclosure in complex forms
Use conditional fields to create wizard-like forms. Show basic fields first, then reveal additional fields based on user choices. For instance, show payment fields only after a user selects a paid membership option.
Conditional field groups with inheritance
Configure a field group containing multiple related fields to appear/hide based on a single control field. Use the inheritance feature to propagate the visibility condition to all fields within the group with a single dependency configuration.
Multi-step validation with conditional requirements
Make fields required conditionally based on other selections. For example, if 'Contact Method' is set to 'Email', make the email field required; if set to 'Phone', make the phone number field required instead.
Hide inapplicable options in entity reference fields
Use conditional fields to show or hide entire sections of a form based on entity reference selections. For example, when selecting a specific category in a taxonomy reference, show fields relevant only to that category.
Paragraph-based conditional content
Within paragraph types, create conditional fields that show different options based on paragraph configuration. For example, in a 'Media' paragraph type, show video URL fields when 'Video' is selected and image upload fields when 'Image' is selected.
Tips
- Use the 'Insert value from widget' option when possible, as it provides the most accurate value matching by using the actual field widget for input.
- When configuring multiple dependencies on the same field, carefully consider the grouping (AND/OR/XOR) to achieve the desired logic.
- For complex forms, test dependencies thoroughly with different value combinations to ensure all scenarios work as expected.
- Use browser developer tools to inspect the generated #states array if dependencies aren't working as expected.
- Remember that conditional fields only affect the form display; server-side validation and field storage are handled separately.
- For paragraph types, always configure dependencies on the paragraph type edit form, not from the parent entity type.
- Use the inheritance feature for field groups to reduce the number of individual dependencies you need to configure.
- When using regular expressions, test them in both PHP and JavaScript environments as syntax can differ slightly.
- Consider using the 'Reset to default values' option for fields that should clear when their dependency is no longer triggered.
- The module respects Drupal's permission system; ensure users have appropriate permissions to view and manage conditional fields.
Technical Details
Admin Pages 10
/admin/structure/conditional_fields
Main administration page listing all entity types that support conditional fields. Click on an entity type to view its bundles and configure field dependencies.
/admin/structure/conditional_fields/{entity_type}
Lists all bundles (content types, media types, etc.) for the selected entity type. Click on a bundle to configure its field dependencies.
/admin/structure/conditional_fields/{entity_type}/{bundle}
Configure conditional field dependencies for a specific entity bundle. View existing dependencies and add new ones. Each dependency defines a target field (dependent) that reacts to a control field (dependee) based on specified conditions.
/admin/structure/conditional_fields/{entity_type}/{bundle}/{field_name}/{uuid}/edit
Detailed configuration form for a specific field dependency. Configure the exact condition values, visual effects, and advanced options.
/admin/structure/types/manage/{node_type}/conditionals
Tab on node type edit page for managing conditional field dependencies for this content type.
/admin/structure/media/manage/{media_type}/conditionals
Tab on media type edit page for managing conditional field dependencies for this media type.
/admin/structure/block/manage/block-content/{block_content_type}/conditionals
Tab on custom block type edit page for managing conditional field dependencies for this block type.
/admin/structure/comment/manage/{comment_type}/conditionals
Tab on comment type edit page for managing conditional field dependencies for this comment type.
/admin/config/people/accounts/conditionals
Tab on user account settings page for managing conditional field dependencies for user profiles.
/admin/structure/paragraphs_type/{paragraphs_type}/conditionals
Tab on paragraph type edit page for managing conditional field dependencies for this paragraph type. Requires the Paragraphs module.
Permissions 3
Hooks 8
hook_conditional_fields
Build a list of available fields for conditional field configuration. Allows modules to register pseudo-fields (like those from Field Group) that are not standard Field API fields.
hook_conditional_fields_alter
Alter the list of available fields for conditional field configuration. Use this to modify, sort, or filter the field list.
hook_conditional_fields_children
Return a list of fields contained within a given parent field. Used by modules that provide container fields (like Field Group, Paragraphs) to enable inheritance of conditional settings.
hook_conditional_fields_children_alter
Alter the list of fields contained within a parent field. Allows modification of the child field list for inheritance purposes.
hook_conditionalFieldsStates_alter
Alter the list of available states that can be applied to dependent fields.
hook_conditionalFieldsConditions_alter
Alter the list of available conditions for evaluating dependencies.
hook_conditionalFieldsEffects_alter
Alter the list of available visual effects for state changes.
hook_conditional_fields_priority_field_alter
Alter the list of field types that have priority for dependency processing. Used for fields like datelist that require special handling.
Troubleshooting 6
Ensure the form is properly rebuilt after AJAX calls. The conditional_fields library needs to be attached to the form. Check that Drupal behaviors are properly triggering on AJAX content. If using custom AJAX, ensure drupalSettings.conditionalFields is updated.
The module automatically removes required validation from hidden fields. If you still see errors, check that the field is properly configured with a visibility state. Also verify the dependency is evaluated before form validation by checking the form's #after_build order.
Ensure dependencies are configured on the paragraph type itself, not the parent entity. For paragraphs, navigate to the specific paragraph type's 'Manage dependencies' tab. Also check that the paragraph widget's form mode matches where dependencies are configured.
Verify the selector syntax is valid jQuery. Test the selector in browser console first. Remember to use %lang placeholder for translatable fields and %key for multi-value field components. The selector should target the actual form input, not its wrapper.
Check that the conditional_fields/conditional_fields library is loaded. Verify there are no JavaScript errors in the console. The effects only work with visible/!visible states. Ensure the effect speed is a valid number in milliseconds.
Check the condition configuration. For states like 'visible when checked', the inverse '!visible when unchecked' should work automatically. If using value conditions, ensure all possible values are accounted for in your logic.