webform_term_hierarchical_checkboxes

Webform Term Hierarchical Checkboxes provides a custom Webform element that renders a taxonomy vocabulary's terms as collapsible, hierarchical checkboxes.

By default only the root-level (depth 0) terms are visible. Checking a parent term reveals its direct children; unchecking a parent hides and deselects all its descendants. This behaviour works for any number of nesting levels.

Parent terms act purely as expand/collapse toggles. Only leaf-level terms (terms with no children) are ever submitted and stored as values.

Key features

• Works with any taxonomy vocabulary, at any number of nesting levels.
• Collapsible tree: children are hidden until the parent is checked.
• Only deepest-level (leaf) terms are saved as submission values.
• Optional validation rule: require at least one leaf-level term to be selected before the form can be submitted.
• Progressive indentation based on term depth, rendered with CSS custom properties.

Requirements

Drupal 10 or 11
Webform module
Core Taxonomy module (drupal:taxonomy)
No additional libraries or composer packages are required.

Installation

Place the module folder inside web/modules/custom/ (or any modules directory that is scanned by Drupal).

Enable the module through the Drupal admin UI at Administration > Extend, or with Drush:
drush en webform_term_hierarchical_checkboxes

Configuration

Adding the element to a webform
Navigate to Administration > Structure > Webforms and open or create the desired webform.
Click Build to open the form builder.
Click Add element.
In the category Entity reference elements, select Term hierarchical checkboxes.
Configure the element in the dialog that opens (see settings below).
Click Save and then Save elements.

When a vocabulary has only one level of terms (no children), all terms behave as selectable leaves and the hierarchy toggle has no effect.

How it works

Browser behaviour (JavaScript)
On page load, all child terms (depth > 0) are hidden.
Checking a parent term reveals its direct children.
Unchecking a parent term hides and deselects all descendants recursively.
The caret icon (▶) next to a parent label rotates 90° when the parent is expanded.
Server-side value handling
All checked values are sent to the server on submission.
The server-side validate callback strips any checked parent (expander) terms before the values are saved. Only leaf-level term IDs are stored in the submission.
This stripping happens before Webform's own multiple-value count validation, so a configured Maximum number of values limit is evaluated against leaf selections only.