@zag-js/cascade-select

@zag-js/cascade-select

Core logic for the cascade select widget implemented as a state machine

A comprehensive state machine for building cascade select (cascading dropdowns) components with hierarchical data navigation.

Features

Hierarchical Data Support

• Navigate through nested data structures (continents → countries → states)
• Support for unlimited depth levels
• Dynamic level generation based on data structure
• Efficient tree collection management

Full Keyboard Navigation

• Arrow keys: Navigate between items and levels
• Home/End: Jump to first/last item at any level
• Enter/Space: Select items or navigate into children
• Escape: Close dropdown and return focus
• Arrow Left/Right: Navigate between parent and child levels

Flexible Selection Modes

• Single selection: Choose one complete path
• Multiple selection: Select multiple paths simultaneously
• Parent selection: Allow selection of non-leaf items (optional)
• Leaf-only selection: Restrict selection to final items only

Interaction Models

• Click highlighting: Navigate by clicking items
• Hover highlighting: Navigate by mouse hover with grace areas
• Mixed interaction: Combine click and hover behaviors
• Touch-friendly: Optimized for mobile interactions

Accessibility Built-in

• ARIA compliance: Proper roles, states, and properties
• Screen reader support: Descriptive labels and live regions
• Focus management: Logical tab order and focus restoration
• Keyboard-only operation: Complete functionality without mouse

Customizable Behavior

• Auto-close options: Control when dropdown closes after selection
• Custom separators: Configure path display formatting
• Disabled items: Mark items as non-selectable
• Read-only mode: Display-only state
• Loop navigation: Circular navigation within levels

UI Integration

• Positioning system: Intelligent dropdown placement with collision detection
• Scroll management: Auto-scroll highlighted items into view
• Level indicators: Visual representation of navigation depth
• Loading states: Handle async data loading
• Empty states: Graceful handling of empty data sets

Developer Experience

• Event callbacks: onChange, onHighlight, onOpen/Close events
• Custom formatting: Control display text and value representation
• Form integration: Works with native form elements and validation
• TypeScript support: Full type safety for data structures

Common Use Cases

• Geographic selection: Country → State → City
• Category browsing: Department → Category → Subcategory → Product
• Organizational hierarchy: Company → Division → Team → Employee
• File system navigation: Folder → Subfolder → File
• Menu systems: Main Menu → Submenu → Action

Installation

yarn add @zag-js/cascade-select
# or
npm i @zag-js/cascade-select

Contribution

Yes please! See the contributing guidelines for details.

Licence

This project is licensed under the terms of the MIT license.