react-cascading-menu
Version:
A powerful React cascading dropdown component with multi-selection, search functionality, and hierarchical navigation. Perfect for building category selectors, dependent dropdowns, and nested menu systems with TypeScript support.
206 lines (165 loc) • 7.91 kB
Markdown
# React Cascading Menu
[](https://badge.fury.io/js/react-cascading-menu)
[](https://opensource.org/licenses/MIT)
A powerful, customizable **React cascading dropdown menu component** with multi-selection, search functionality, and hierarchical navigation. Perfect for building complex category selectors, dependent dropdowns, and nested menu systems.
**Cascading Menu** is a multi-selectable cascading menu component for React. It enhances user experience and navigation efficiency with the following features:
- **Navigation Efficiency**: Searching and selecting options in traditional dependent dropdowns is difficult and time-consuming as the user needs to navigate through multiple dropdowns. Cascading Menu provides easy access to options through interactive selection or global search, making selection faster and more efficient.
- **Enhanced User Experience**: Understanding relationships between options in dependent dropdowns can be challenging. Cascading Menu provides a clear visual representation of the option hierarchy.
## Key Benefits
- **Global Search**: Find options quickly across all levels
- **Multi-Selection**: Select multiple items at any level
- **Customizable Themes**: Light/dark themes with custom styling
- **Layout Flexibility**: Horizontal and vertical orientations
## Features
1. **Layout Mode/Orientation** - Switch between horizontal and vertical layouts
2. **Visual Hierarchy and Context Clarity** - Clear parent-child relationships
3. **Tag-Based Navigation and Deletion** - Easy selection management
4. **Interactive Selection and Deletion** - Click to select/deselect
5. **Search Capability** - Global search across all menu levels
6. **Multi/Single-Select Flexibility** - Configure selection mode per level
7. **Maintains Selection Order** - Preserves user selection sequence
8. **Theme Customization Options** - Light/dark themes with custom styling
## Use Cases
- **E-commerce Category Filters**: Product categorization (Electronics > Laptops > Gaming)
- **Location Selectors**: Country > State > City > Area selection
- **Organizational Hierarchies**: Department > Team > Role selection
- **Content Management**: Topic > Subtopic > Tag organization
- **Configuration Panels**: Settings with nested options
## Installation
```sh
npm install react-cascading-menu
```
## 🎬 Demo
[**🔗 Live Demo**](https://vinayv-456.github.io/react-cascading-menu/) | [**📖 Documentation**](https://github.com/vinayv-456/react-cascading-menu#readme)
## 🚀 Quick Start
```jsx
import React, { useRef, useState } from "react";
import ReactCascadingMenu from "react-cascading-menu";
import { menuGroup } from "./data.js";
const CascadingMenu = () => {
const ref = useRef();
const [layout, setLayout] = useState("vertical");
const fetchSelectionItemsLabels = () => {
console.log(
"get selections as label array",
ref.current?.getAllItemsSelected()
);
};
const fetchSelectionItems = () => {
console.log("get selections", ref.current?.getSelection());
};
const changeLayout = () => {
setLayout((prev) => (prev === "horizontal" ? "vertical" : "horizontal"));
};
return (
<>
<ReactCascadingMenu
layout={layout}
ref={ref}
menuGroup={menuGroup}
// selectedItems={preSelectedItems}
isMultiSelection={true}
displayValue="label"
width={layout === "vertical" ? "40vw" : "60vw"}
height="400px"
theme="light"
/>
<br />
<button className="btn" onClick={fetchSelectionItems}>
get selections
</button>
<button className="btn" onClick={fetchSelectionItemsLabels}>
get selections as label array
</button>
<span>(Check console logs for results)</span>
<div className="md-top">
<button className="btn" onClick={changeLayout}>
Change layout
</button>
</div>
</>
);
};
export default CascadingMenu;
```
### Data Example
```jsx
const menuGroup = {
id: "1_101",
groupHeading: "Country",
options: [
{
id: "2_101",
label: "United States",
value: "United States",
groupHeading: "State",
options: [
{
id: "3_101",
label: "New York",
value: "New York",
groupHeading: "City",
options: [
{
id: "4_101",
label: "New York City",
value: "New York City",
groupHeading: "Place",
isMultiSelection: false,
options: [
{
id: "5_101",
label: "Statue of Liberty",
value: "Statue of Liberty",
},
{
id: "5_102",
label: "Central Park",
value: "Central Park",
},
{
id: "5_103",
label: "Empire State Building",
value: "Empire State Building",
},
],
},
],
},
],
},
],
};
```
## Screenshots
## 🛠️ API Reference
### Props
| Prop | Type | Default | Description |
| ------------------ | ---------------------------- | ------------ | --------------------------- |
| `menuGroup` | `MenuGroup` | required | Hierarchical data structure |
| `isMultiSelection` | `boolean` | `true` | Enable multi-selection |
| `layout` | `'horizontal' \| 'vertical'` | `'vertical'` | Menu orientation |
| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
| `width` | `string` | `'100%'` | Component width |
| `height` | `string` | `'300px'` | Component height |
| `displayValue` | `string` | `'label'` | Key to display from options |
| `selectedItems` | `SelectedItem[]` | `[]` | Pre-selected items |
### Methods
| Method | Returns | Description |
| ----------------------- | ---------------- | ---------------------------- |
| `getSelection()` | `SelectedItem[]` | Get all selected items |
| `getAllItemsSelected()` | `string[]` | Get selected labels as array |
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [NPM Package](https://www.npmjs.com/package/react-cascading-menu)
- [GitHub Repository](https://github.com/vinayv-456/react-cascading-menu)
- [Live Demo](https://vinayv-456.github.io/react-cascading-menu/)
- [Report Issues](https://github.com/vinayv-456/react-cascading-menu/issues)
## 🏷️ Keywords
`react` `dropdown` `cascading` `menu` `select` `multiselect` `search` `navigation` `ui-component` `typescript` `styled-components` `hierarchical` `tree-select` `category-selector` `dependent-dropdown`