Package Exports

@iazadur/hierarchical-select
@iazadur/hierarchical-select/dist/index.esm.js
@iazadur/hierarchical-select/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@iazadur/hierarchical-select) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Hierarchical Select

A production-ready React component for hierarchical (dependent) dropdowns, designed for both Ant Design and Shadcn UI.

📖 Live Documentation & Demos

Check out our interactive component documentation to see live examples and explore all features.

✨ Features

Hierarchical Dependency: Support for up to 5 select fields with parent-child relationships
Single and Multiple Select: Configure fields for single or multiple selection
Dynamic Loading: Load options statically or fetch dynamically from APIs
Design System Integration: Seamless integration with both Ant Design and Shadcn UI
Fully Customizable: Customize labels, placeholders, error messages, and styling
TypeScript Support: Fully typed with comprehensive type definitions
Accessibility: WAI-ARIA compliant with keyboard navigation support
Performance Optimized: Memoization, lazy loading, and response caching

🚀 Installation

npm install @iazadur/hierarchical-select

# Peer dependencies
npm install react react-dom

With Ant Design

npm install antd

With Shadcn UI

npm install @radix-ui/react-select

💻 Basic Usage

import React from "react";
import HierarchicalSelect from "@iazadur/hierarchical-select";

const App = () => {
  const fields = [
    {
      index: 0,
      options: [
        { value: "us", label: "United States" },
        { value: "ca", label: "Canada" },
        { value: "uk", label: "United Kingdom" },
      ],
      placeholder: "Select Country",
      label: "Country",
    },
    {
      index: 1,
      options: [],
      placeholder: "Select Region",
      label: "Region",
      fetchOptions: async (parentValue) => {
        // Fetch regions based on selected country
        // Simulated API call with static data
        await new Promise((resolve) => setTimeout(resolve, 500));

        const regions = {
          us: [
            { value: "ca", label: "California" },
            { value: "ny", label: "New York" },
          ],
          ca: [
            { value: "on", label: "Ontario" },
            { value: "qc", label: "Quebec" },
          ],
          uk: [
            { value: "eng", label: "England" },
            { value: "sct", label: "Scotland" },
          ],
        };

        return regions[parentValue] || [];
      },
    },
    {
      index: 2,
      options: [],
      placeholder: "Select City",
      label: "City",
      multiple: true, // Allow multiple selections
      fetchOptions: async (parentValue) => {
        // Fetch cities based on selected region
        await new Promise((resolve) => setTimeout(resolve, 500));

        const cities = {
          ca: [
            { value: "sf", label: "San Francisco" },
            { value: "la", label: "Los Angeles" },
          ],
          ny: [
            { value: "nyc", label: "New York City" },
            { value: "buf", label: "Buffalo" },
          ],
          // ... more cities
        };

        return cities[parentValue] || [];
      },
    },
  ];

  return (
    <HierarchicalSelect
      fields={fields}
      designSystem="shadcn" // or "antd"
      onChange={(values) => console.log("Selected:", values)}
      onError={(error) => console.error("Error:", error)}
    />
  );
};

export default App;

🎨 Custom Styling

The component supports custom styling to match your application design. You can add custom styles to each field:

<HierarchicalSelect
  fields={[
    {
      index: 0,
      options: [...],
      // Custom styling
      className: 'my-custom-field',
      customStyle: {
        background: '#f8fafc',
        padding: '12px',
        borderRadius: '8px'
      },
      // Style just the select element
      selectClassName: 'my-custom-select',
      selectStyle: { borderWidth: '2px' }
    },
    // ...more fields
  ]}
  designSystem="shadcn"
/>

📝 API Reference