Category Picker

Category Picker gives you a drill-down, searchable modal for choosing an entry from a large hierarchy. That can be taxonomy terms, or any content entity type that has a self-referencing parent entity-reference field. Instead of a 17,000-option dropdown, or an autocomplete that only helps if you already know the term name, editors browse the tree one level at a time, or type a few characters and pick from a list of full ancestor paths.

Requirements

Drupal 10.3 or newer, or any Drupal 11 release. The main module has no non-core dependencies. Full details, including what the optional sub-modules need, are in the documentation.

Installation

Install with composer require drupal/category_picker, then enable it at Extend (or run drush en category_picker). Enable the category_picker_views sub-module (needs core Views) and/or category_picker_facets (needs the contributed Facets module) only if you want those integrations.

Category Picker was built first for Drupal Commerce: filing products and product-variation types into a category vocabulary that can run to thousands of terms, then reusing that same tree in Views, in Facets, and over a Search API index on the storefront. It works just as happily for any other hierarchy. The module has no non-core dependencies, uses an optimised TermStorage fast-path for plain taxonomy, and keeps the Views and Facets pieces as optional sub-modules you turn on only when you need them.

Configuration

There is no global settings page. Everything is configured per field, per view, or per facet.

1. Add or edit an entity_reference field pointing at a hierarchical target: a taxonomy vocabulary, or any entity type with a self-referencing parent field.
2. At Manage form display, set the widget to Category picker (modal) and adjust its settings: display mode (modal or inline), hierarchy field, which rows are selectable (leaf mode and leaf field), path separator, search threshold, modal width, and modal title.
3. Optionally, at Manage display, set the formatter to Ancestor path (breadcrumb).
4. Views filter: add the "… (category picker modal)" filter to a view.
5. Facets widget: set a facet's widget to Category tree (category picker) and enable Facets' Transform entity ID to label and Hierarchy processors.

Features

• Drill-down modal. One level at a time, with a breadcrumb trail and a Back control.
• Type-ahead search. Matches are shown as full Root › Branch › Leaf paths, so two leaves with the same name are never ambiguous.
• Single or multi-value. Multi-value selections render as a native Drupal tabledrag table, so you can drag to reorder, remove a row, or show row weights.
• Inline mode. Drop the tree permanently under the field instead of behind a button.
• Entity-type agnostic. Taxonomy terms, nodes, custom entities, anything with a self-referencing parent field.
• Configurable "selectable" rule. Allow picking only leaves, only rows flagged by a boolean field, or any row at all.
• Ancestor-path formatter. Render the stored value as a linked Root › Branch › Leaf breadcrumb.
• Self-contained. The element refreshes its own markup through a hidden update submit, so the host form needs no #ajax wiring.
• Translatable. Every label, breadcrumb and path is resolved to the active content language.
• Accessible. Built on Drupal's core dialog, with keyboard arrow-key navigation, screen-reader announcements on every level change, and ARIA roles throughout the tree.
• Themeable and alterable. Five Twig templates with per entity-type and per-bundle suggestions, plus six alter hooks.

The Facets widget needs both the Transform entity ID to label and Hierarchy processors enabled on the facet, or the tree renders flat and shows raw IDs.

Widget settings

Display mode

Pop-up dialog, or an inline tree always visible under the field.

Hierarchy field

The self-referencing parent field on the target entity type. Defaults to parent.

Selectable rows (leaf mode)

No children (leaves only), only rows flagged by a boolean field, or any row. When a boolean field is used, its machine name is validated on save.

Path separator

The string placed between path segments. Defaults to › .

Search minimum characters

How many characters before a search fires.

Modal width / Modal title

Dialog size, and the dialog heading. The open button reads "Choose a category" while empty, and switches to core's "Add another item" once a multi-value field has a row.

Show the full category path

When off, chips and the open button show only the picked row's own name; the full path stays available as a tooltip.

Accessibility

The modal is Drupal core's AJAX dialog, so it traps focus while open, closes on Escape, and returns focus to the button that opened it, with focus landing on the search box when it appears. Every row is a real link or labelled control, arrow keys move a roving focus through the list, and screen-reader users hear a live announcement on every level change, pick and removal. Full details are in the documentation.

Dark mode, RTL and translation

The modal follows your visitor's light or dark preference automatically, ships full right-to-left support, and every label, breadcrumb and path is translated to the active content language. Full details are in the documentation.

How it compares

• Against a plain autocomplete: you don't need to know the term name up front, because you can browse instead.
• Against a native select list or dynamic select tree: it scales to tens of thousands of terms without shipping the whole vocabulary to the browser.
• Against tag-style widgets such as Tagify: no third-party JS dependency, and a real drill-down for hierarchies rather than a flat tag field.
• Against taxonomy-only pickers: it works with any entity type that has a parent reference field, not just taxonomy_term.

Uninstalling

If the module is uninstalled, affected fields fall back to Drupal's default entity-reference widget and formatter.

📖 Category Picker guide

Category Picker's goal is to make large hierarchical reference fields comfortable for editors, whether that is a deep vocabulary, a product taxonomy, an org chart, or any other entity tree. Try it on your own hierarchies and tell us what breaks. Feedback and patches are welcome.

See more details:
Category Picker documentation

Related modules

Other approaches to hierarchical reference fields, and modules that pair well with Category Picker.

• Client-side Hierarchical Select, chained select lists for a single taxonomy tree.
• Term Reference Tree, an always-open checkbox or radio tree widget for taxonomy terms.
• Facets, faceted search; required by the category_picker_facets sub-module.
• Search API, the index the Facets tree widget filters against.
• Tagify, a tag-style widget for flat (non-hierarchical) entity reference fields.