or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cascader.mdindex.mdmultiple-selection.mdpanel.mdsearch.md
tile.json

tessl/npm-rc-cascader

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/rc-cascader@3.34.x

To install, run

npx @tessl/cli install tessl/npm-rc-cascader@3.34.0

index.mddocs/

RC Cascader

RC Cascader is a comprehensive cascading select component for React applications that enables hierarchical option selection through a dropdown interface. It offers extensive customization options including custom field mapping, dynamic data loading, search functionality, multiple selection modes, and flexible styling through CSS classes and inline styles.

Package Information

  • Package Name: rc-cascader
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install rc-cascader
  • CSS Import: Import styles from rc-cascader/assets/index.css

Core Imports

import Cascader from "rc-cascader";
import { Panel } from "rc-cascader";

// Access constants via destructuring
const { SHOW_PARENT, SHOW_CHILD } = Cascader;

// Or use Panel from Cascader
const Panel = Cascader.Panel;

For CommonJS:

const Cascader = require("rc-cascader");
const { Panel } = require("rc-cascader");

// Access constants
const { SHOW_PARENT, SHOW_CHILD } = Cascader;

Basic Usage

import React, { useState } from 'react';
import Cascader from 'rc-cascader';
import 'rc-cascader/assets/index.css';

const options = [
  {
    label: '福建',
    value: 'fj',
    children: [
      {
        label: '福州',
        value: 'fuzhou',
        children: [
          {
            label: '马尾',
            value: 'mawei',
          },
        ],
      },
      {
        label: '泉州',
        value: 'quanzhou',
      },
    ],
  },
  {
    label: '浙江',
    value: 'zj',
    children: [
      {
        label: '杭州',
        value: 'hangzhou',
        children: [
          {
            label: '余杭',
            value: 'yuhang',
          },
        ],
      },
    ],
  },
];

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

  const onChange = (value, selectedOptions) => {
    console.log(value, selectedOptions);
    setValue(value);
  };

  return (
    <Cascader options={options} value={value} onChange={onChange}>
      <input placeholder="Please select" />
    </Cascader>
  );
};

Architecture

RC Cascader is built around several key components:

  • Main Cascader Component: Full-featured dropdown cascader with trigger element integration
  • Panel Component: Standalone cascader panel for custom layouts without dropdown behavior
  • Option List System: Multi-column option display with keyboard navigation and accessibility
  • Search Engine: Advanced search with filtering, sorting, and custom rendering capabilities
  • Value Management: Supports both single and multiple selection modes with various display strategies
  • Dynamic Loading: Lazy loading of option data with loading states and error handling

Capabilities

Core Cascader Component

The main cascading select component providing dropdown interface with hierarchical option selection.

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;

interface CascaderProps<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType,
  Multiple extends boolean | React.ReactNode = false
> {
  // Core data and selection
  options?: OptionType[];
  value?: GetValueType<OptionType, ValueField, Multiple>;
  defaultValue?: GetValueType<OptionType, ValueField, Multiple>;
  onChange?: (
    value: GetValueType<OptionType, ValueField, Multiple>,
    selectOptions: GetOptionType<OptionType, Multiple>
  ) => void;
  
  // Selection behavior
  checkable?: Multiple;
  changeOnSelect?: boolean;
  showCheckedStrategy?: ShowCheckedStrategy;
  
  // Field customization
  fieldNames?: FieldNames<OptionType, ValueField>;
  
  // Dynamic loading
  loadData?: (selectOptions: OptionType[]) => void;
  
  // Search functionality
  showSearch?: boolean | ShowSearchType<OptionType>;
  searchValue?: string;
  onSearch?: (value: string) => void;
  autoClearSearchValue?: boolean;
  
  // Dropdown behavior
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  builtinPlacements?: BuildInPlacements;
  getPopupContainer?: (trigger: Node) => Node;
  dropdownMatchSelectWidth?: boolean;
  
  // Styling and display
  prefixCls?: string;
  className?: string;
  style?: React.CSSProperties;
  dropdownClassName?: string;
  dropdownMenuColumnStyle?: React.CSSProperties;
  dropdownStyle?: React.CSSProperties;
  animation?: string;
  transitionName?: string;
  
  // Custom rendering
  displayRender?: (label: string[], selectedOptions?: OptionType[]) => React.ReactNode;
  optionRender?: (option: OptionType) => React.ReactNode;
  
  // Icons
  expandIcon?: React.ReactNode;
  loadingIcon?: React.ReactNode;
  
  // Interaction
  expandTrigger?: 'hover' | 'click';
  disabled?: boolean;
  placeholder?: string;
  notFoundContent?: React.ReactNode;
}

Cascader Component

Panel Component

Standalone cascader panel for custom layouts without dropdown behavior.

function Panel<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType,
  Multiple extends boolean | React.ReactNode = false
>(props: PanelProps<OptionType, ValueField, Multiple>): JSX.Element;

interface PanelProps<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType,
  Multiple extends boolean | React.ReactNode = false
> {
  value?: GetValueType<OptionType, ValueField, Multiple>;
  defaultValue?: GetValueType<OptionType, ValueField, Multiple>;
  changeOnSelect?: boolean;
  onChange?: (
    value: GetValueType<OptionType, ValueField, Multiple>,
    selectOptions: GetOptionType<OptionType, Multiple>
  ) => void;
  options?: OptionType[];
  prefixCls?: string;
  checkable?: Multiple;
  fieldNames?: FieldNames<OptionType, ValueField>;
  showCheckedStrategy?: ShowCheckedStrategy;
  loadData?: (selectOptions: OptionType[]) => void;
  expandTrigger?: 'hover' | 'click';
  expandIcon?: React.ReactNode;
  loadingIcon?: React.ReactNode;
  className?: string;
  style?: React.CSSProperties;
  direction?: 'ltr' | 'rtl';
  notFoundContent?: React.ReactNode;
  disabled?: boolean;
}

Panel Component

Search Functionality

Advanced search capabilities with filtering, custom rendering, and result limiting.

interface ShowSearchType<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType
> {
  filter?: (
    inputValue: string,
    options: OptionType[],
    fieldNames: FieldNames<OptionType, ValueField>
  ) => boolean;
  render?: (
    inputValue: string,
    path: OptionType[],
    prefixCls: string,
    fieldNames: FieldNames<OptionType, ValueField>
  ) => React.ReactNode;
  sort?: (
    a: OptionType[],
    b: OptionType[],
    inputValue: string,
    fieldNames: FieldNames<OptionType, ValueField>
  ) => number;
  matchInputWidth?: boolean;
  limit?: number | false;
}

Search Configuration

Multiple Selection

Multiple selection capabilities with different display strategies and checkbox support.

// Enable multiple selection
checkable: true

// Control display strategy
showCheckedStrategy: 'SHOW_PARENT' | 'SHOW_CHILD'

// Multiple selection value type
type MultipleValueType = (string | number)[][];

// Multiple selection change handler
onChange: (value: MultipleValueType, selectOptions: OptionType[][]) => void;

Multiple Selection

Core Types

interface BaseOptionType {
  disabled?: boolean;
  disableCheckbox?: boolean;
  label?: React.ReactNode;
  value?: string | number | null;
  children?: DefaultOptionType[];
}

type DefaultOptionType = BaseOptionType & Record<string, any>;

interface FieldNames<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType
> {
  label?: keyof OptionType;
  value?: keyof OptionType | ValueField;
  children?: keyof OptionType;
}

type ShowCheckedStrategy = 'SHOW_PARENT' | 'SHOW_CHILD';

// Constants available on Cascader component
Cascader.SHOW_PARENT: 'SHOW_PARENT';
Cascader.SHOW_CHILD: 'SHOW_CHILD';

interface CascaderRef {
  focus: () => void;
  blur: () => void;
}

type GetValueType<
  OptionType extends DefaultOptionType = DefaultOptionType,
  ValueField extends keyof OptionType = keyof OptionType,
  Multiple extends boolean | React.ReactNode = false
> = false extends Multiple
  ? (string | number)[]
  : (string | number)[][];

type GetOptionType<
  OptionType extends DefaultOptionType = DefaultOptionType,
  Multiple extends boolean | React.ReactNode = false
> = false extends Multiple 
  ? OptionType[] 
  : OptionType[][];

// Dropdown positioning types
type Placement = 
  | 'bottomLeft' 
  | 'bottomRight' 
  | 'topLeft' 
  | 'topRight' 
  | 'bottom' 
  | 'top';

interface BuildInPlacements {
  [key: string]: {
    points: string[];
    offset?: number[];
    targetOffset?: number[];
    overflow?: {
      adjustX?: boolean;
      adjustY?: boolean;
    };
  };
}