tessl/npm-rc-cascader

A comprehensive cascading select component for React applications that enables hierarchical option selection through a dropdown interface

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Cascader Component

Name: tessl/npm-rc-cascader
Author: tessl

The main cascading select component providing dropdown interface with hierarchical option selection. Supports single and multiple selection modes, search functionality, dynamic loading, and extensive customization options.

Capabilities

Main Cascader Component

Creates a cascading select dropdown with trigger element integration.

/**
 * Main cascading select component with dropdown interface
 * @param props - Cascader configuration props
 * @returns JSX.Element
 */
function Cascader<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType,
  Multiple extends boolean | React.ReactNode = false
>(props: CascaderProps<OptionType, ValueField, Multiple>): JSX.Element;

Core Data Props

Properties for managing options data and selection values.

interface CoreDataProps<
  OptionType extends DefaultOptionType,
  ValueField extends keyof OptionType,
  Multiple extends boolean | React.ReactNode
> {
  /** Hierarchical options data array */
  options?: OptionType[];
  
  /** Controlled selected value */
  value?: GetValueType<OptionType, ValueField, Multiple>;
  
  /** Initial selected value for uncontrolled mode */
  defaultValue?: GetValueType<OptionType, ValueField, Multiple>;
  
  /** Selection change callback */
  onChange?: (
    value: GetValueType<OptionType, ValueField, Multiple>,
    selectOptions: GetOptionType<OptionType, Multiple>
  ) => void;
}

Selection Behavior Props

Configure how selections are handled and displayed.

interface SelectionBehaviorProps<Multiple extends boolean | React.ReactNode> {
  /** Enable multiple selection mode */
  checkable?: Multiple;
  
  /** Trigger onChange on each level selection, not just leaf nodes */
  changeOnSelect?: boolean;
  
  /** Strategy for displaying selected items in multiple mode */
  showCheckedStrategy?: ShowCheckedStrategy;
}

Field Customization Props

Customize how option object fields are interpreted.

interface FieldCustomizationProps<
  OptionType extends DefaultOptionType,
  ValueField extends keyof OptionType
> {
  /** Custom field name mapping */
  fieldNames?: FieldNames<OptionType, ValueField>;
}

interface FieldNames<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType
> {
  /** Field name for option display label (default: 'label') */
  label?: keyof OptionType;
  
  /** Field name for option value (default: 'value') */
  value?: keyof OptionType | ValueField;
  
  /** Field name for child options (default: 'children') */
  children?: keyof OptionType;
}

Dynamic Loading Props

Support for lazy loading of option data.

interface DynamicLoadingProps<OptionType extends DefaultOptionType> {
  /** Callback for loading child options dynamically */
  loadData?: (selectOptions: OptionType[]) => void;
  
  /** Custom loading icon */
  loadingIcon?: React.ReactNode;
}

Search Props

Search functionality configuration.

interface SearchProps<
  OptionType extends DefaultOptionType,
  ValueField extends keyof OptionType
> {
  /** Enable search with boolean or advanced configuration */
  showSearch?: boolean | ShowSearchType<OptionType, ValueField>;
  
  /** Controlled search input value */
  searchValue?: string;
  
  /** Search input change callback */
  onSearch?: (value: string) => void;
  
  /** Clear search value when selecting an item (multiple mode only) */
  autoClearSearchValue?: boolean;
}

Dropdown Behavior Props

Control dropdown visibility and positioning.

interface DropdownBehaviorProps {
  /** Control dropdown visibility */
  open?: boolean;
  
  /** Dropdown visibility change callback */
  onOpenChange?: (open: boolean) => void;
  
  /** Dropdown placement relative to trigger */
  placement?: Placement;
  
  /** Custom placement configurations */
  builtinPlacements?: BuildInPlacements;
  
  /** Custom container for dropdown portal */
  getPopupContainer?: (trigger: Node) => Node;
}

Styling Props

Appearance and styling customization.

interface StylingProps {
  /** CSS class prefix (default: 'rc-cascader') */
  prefixCls?: string;
  
  /** Additional CSS classes for root element */
  className?: string;
  
  /** Inline styles for root element */
  style?: React.CSSProperties;
  
  /** Additional CSS classes for dropdown */
  dropdownClassName?: string;
  
  /** Inline styles for dropdown menu columns */
  dropdownMenuColumnStyle?: React.CSSProperties;
}

Custom Rendering Props

Customize how options and selections are displayed.

interface CustomRenderingProps<OptionType extends DefaultOptionType> {
  /** Custom display rendering for selected values */
  displayRender?: (
    label: string[],
    selectedOptions?: OptionType[]
  ) => React.ReactNode;
  
  /** Custom rendering for individual options */
  optionRender?: (option: OptionType) => React.ReactNode;
}

Interaction Props

Control user interaction behavior.

interface InteractionProps {
  /** How to expand option menus: 'hover' or 'click' */
  expandTrigger?: 'hover' | 'click';
  
  /** Disable the entire component */
  disabled?: boolean;
  
  /** Placeholder text for trigger input */
  placeholder?: string;
  
  /** Content to show when no options found */
  notFoundContent?: React.ReactNode;
  
  /** Custom expand icon */
  expandIcon?: React.ReactNode;
}

Usage Examples

Basic Single Selection

import React, { useState } from 'react';
import Cascader from 'rc-cascader';

const options = [
  {
    label: 'Zhejiang',
    value: 'zhejiang',
    children: [
      {
        label: 'Hangzhou',
        value: 'hangzhou',
        children: [
          { label: 'West Lake', value: 'xihu' }
        ]
      }
    ]
  }
];

const BasicExample = () => {
  const [value, setValue] = useState([]);

  return (
    <Cascader
      options={options}
      value={value}
      onChange={(value, selectedOptions) => {
        setValue(value);
        console.log('Selected:', value, selectedOptions);
      }}
      placeholder="Please select"
    />
  );
};

With Search

const SearchExample = () => {
  return (
    <Cascader
      options={options}
      showSearch={{
        filter: (inputValue, path) =>
          path.some(option => 
            option.label.toLowerCase().includes(inputValue.toLowerCase())
          ),
        limit: 50
      }}
      placeholder="Search locations"
    />
  );
};

Dynamic Loading

const DynamicExample = () => {
  const [options, setOptions] = useState(initialOptions);

  const loadData = (selectedOptions) => {
    const targetOption = selectedOptions[selectedOptions.length - 1];
    targetOption.loading = true;

    // Simulate API call
    setTimeout(() => {
      targetOption.loading = false;
      targetOption.children = [
        { label: 'Dynamic Child 1', value: 'child1' },
        { label: 'Dynamic Child 2', value: 'child2' }
      ];
      setOptions([...options]);
    }, 1000);
  };

  return (
    <Cascader
      options={options}
      loadData={loadData}
      changeOnSelect
    />
  );
};

Custom Field Names

const customOptions = [
  {
    title: 'Group 1',
    id: 'group1',
    items: [
      { title: 'Item 1', id: 'item1' }
    ]
  }
];

const CustomFieldsExample = () => {
  return (
    <Cascader
      options={customOptions}
      fieldNames={{
        label: 'title',
        value: 'id',
        children: 'items'
      }}
    />
  );
};

Install with Tessl CLI