# @zag-js/cascade-select > Core logic for the cascade-select widget implemented as a state machine Latest version **1.44.0** (published 2026-09-13) · MIT license · 0 weekly downloads ## Install ```sh npm install @zag-js/cascade-select pnpm add @zag-js/cascade-select yarn add @zag-js/cascade-select bun add @zag-js/cascade-select ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 1.44.0 | | Published | 2026-09-13 | | First published | 2026-02-19 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 10 | | Unpacked size | 154.1 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 5217 | | Author | Abraham Aremu | | Maintainers | segunadebayo | | Keywords | js, machine, xstate, statechart, component, chakra ui, cascade-select | ## Links - npm: https://www.npmjs.com/package/@zag-js/cascade-select - Repository: https://github.com/chakra-ui/zag/tree/main/packages/machines/cascade-select - Homepage: https://github.com/chakra-ui/zag#readme - Issues: https://github.com/chakra-ui/zag/issues - npm.io page: https://npm.io/package/@zag-js/cascade-select ## Dependencies (10) - [@zag-js/core](https://npm.io/package/@zag-js/core.md) 1.44.0 - [@zag-js/types](https://npm.io/package/@zag-js/types.md) 1.44.0 - [@zag-js/utils](https://npm.io/package/@zag-js/utils.md) 1.44.0 - [@zag-js/popper](https://npm.io/package/@zag-js/popper.md) 1.44.0 - [@zag-js/anatomy](https://npm.io/package/@zag-js/anatomy.md) 1.44.0 - [@zag-js/dom-query](https://npm.io/package/@zag-js/dom-query.md) 1.44.0 - [@zag-js/collection](https://npm.io/package/@zag-js/collection.md) 1.44.0 - [@zag-js/rect-utils](https://npm.io/package/@zag-js/rect-utils.md) 1.44.0 - [@zag-js/dismissable](https://npm.io/package/@zag-js/dismissable.md) 1.44.0 - [@zag-js/focus-visible](https://npm.io/package/@zag-js/focus-visible.md) 1.44.0 ## Alternatives - [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads - [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads - [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads - [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads - [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads ## Recent versions - 1.44.0 (latest) — 2026-09-13 - 2.0.0-next.3 (next) — 2026-09-14 - 2.0.0-next.2 — 2026-08-31 - 1.43.3 — 2026-08-20 - 1.43.2 — 2026-08-20 - 1.43.1 — 2026-08-16 - 2.0.0-next.1 — 2026-08-01 - 1.43.0 — 2026-07-29 - 1.42.0 — 2026-06-29 - 1.41.2 — 2026-06-05 - 2.0.0-next.0 — 2026-06-04 - 1.41.1 — 2026-05-26 - 1.41.0 — 2026-05-21 - 1.40.0 — 2026-04-11 - 1.39.1 — 2026-04-05 - … 12 more at https://npm.io/package/@zag-js/cascade-select/versions ## README # @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 ```sh yarn add @zag-js/cascade-select # or npm i @zag-js/cascade-select ``` ## Contribution Yes please! See the [contributing guidelines](https://github.com/chakra-ui/zag/blob/main/CONTRIBUTING.md) for details. ## Licence This project is licensed under the terms of the [MIT license](https://github.com/chakra-ui/zag/blob/main/LICENSE). --- _Source: https://npm.io/package/@zag-js/cascade-select · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._