How to Build Cascaded Dropdowns with Ant Design's Cascader Component

Use the Cascader component from antd with a hierarchical options array, and configure showSearch for filtering or multiple for checkbox selection.

The Cascader component in the ant-design/ant-design repository provides a complete solution for building cascaded dropdowns—multi-level select menus where each choice reveals subsequent options. Implemented in components/cascader/index.tsx, this component wraps the underlying @rc-component/cascader library while adding Ant Design-specific theming, form integration, and accessibility features.

Understanding the Cascader Architecture

The component architecture separates concerns between the main wrapper and the panel UI. The entry point at components/cascader/index.tsx handles prop merging, context consumption, and forwarding to RcCascader (lines 37–38). It calculates merged values for size, status, and disabled state (lines 48–74) by combining explicit props with ConfigProvider context.

For scenarios requiring a standalone panel without the dropdown trigger, components/cascader/Panel.tsx exports Cascader.Panel. This file (lines 85–96) forwards all relevant props to the underlying @rc-component/cascader panel while applying Ant Design icon and styling hooks.

Building Basic Cascaded Dropdowns

To build cascaded dropdowns, define your hierarchical data using the BaseOptionType structure exported from the component. Each option object requires label and value fields, with an optional children array containing the next level.

import React from 'react';
import { Cascader } from 'antd';

const options = [
  {
    label: 'Asia',
    value: 'asia',
    children: [
      { label: 'China', value: 'china' },
      { label: 'Japan', value: 'japan' },
    ],
  },
  {
    label: 'Europe',
    value: 'europe',
    children: [
      { label: 'Germany', value: 'germany' },
      { label: 'France', value: 'france' },
    ],
  },
];

export default () => (
  <Cascader
    options={options}
    placeholder="Please select"
    style={{ width: 250 }}
  />
);

The options prop is forwarded directly to the underlying RcCascader implementation (lines 37–38 of index.tsx), which handles the recursive rendering of dropdown levels.

Enabling Search and Multiple Selection

For enhanced usability, configure showSearch to enable keyword filtering across all levels, or set multiple to render checkboxes for multi-selection.

Search Configuration

Set showSearch to true to activate the default search implementation, or provide a SearchConfig object for custom filtering logic. The default search render function is defined in components/cascader/index.tsx (lines 15–35).

<Cascader
  options={options}
  showSearch
  placeholder="Search locations"
  style={{ width: 300 }}
/>

Multiple Selection

Enable multiple to allow users to select multiple leaf nodes. This prop triggers the useCheckable hook (lines 65–66 of index.tsx), which adds the checkable flag to the inner panel configuration, rendering checkboxes for each option.

import React from 'react';
import { Cascader } from 'antd';

const options = [
  {
    label: 'Fruit',
    value: 'fruit',
    children: [
      { label: 'Apple', value: 'apple' },
      { label: 'Banana', value: 'banana' },
    ],
  },
  {
    label: 'Vegetables',
    value: 'vegetables',
    children: [
      { label: 'Carrot', value: 'carrot' },
      { label: 'Broccoli', value: 'broccoli' },
    ],
  },
];

export default () => (
  <Cascader
    multiple
    options={options}
    placeholder="Select items"
    style={{ width: 300 }}
  />
);

Customizing the Dropdown Panel

When you need to modify the dropdown container—such as adding a footer or header—use the popupRender prop. This function receives the default menu element and returns a React element.

import React from 'react';
import { Cascader } from 'antd';

const options = [ /* hierarchical data */ ];

function footerRender(menu: React.ReactElement) {
  return (
    <div>
      {menu}
      <div style={{ padding: 8, textAlign: 'right' }}>
        <a href="#clear">Clear all</a>
      </div>
    </div>
  );
}

export default () => (
  <Cascader
    options={options}
    popupRender={footerRender}
    style={{ width: 260 }}
  />
);

Internally, popupRender is merged via the usePopupRender hook (lines 23–24 of index.tsx) and passed to RcCascader.

For completely standalone usage without the input trigger, import Cascader.Panel. This is useful for embedding the cascaded selection UI directly into a page layout.

import React from 'react';
import Cascader from 'antd/es/cascader';

const options = [ /* ... */ ];

export default () => (
  <Cascader.Panel
    options={options}
    multiple
    style={{ width: 300 }}
  />
);

The panel component is defined in components/cascader/Panel.tsx and forwards all props to the underlying @rc-component/cascader panel (lines 85–96).

Integrating with Forms and Theming

The Cascader component automatically integrates with Ant Design's Form system. When placed inside a Form.Item, the component consumes FormItemInputContext (lines 65–71 of index.tsx) to inherit validation status, size, and disabled state.

For RTL (Right-to-Left) support, the component respects the global direction context and automatically appends the -rtl class name to the generated class list (lines 44–45 of index.tsx). Icon rendering also adapts to direction via the useIcons hook defined in components/cascader/hooks/useIcons.ts.

Style customization is handled through the variant, bordered, and status props, which are merged with context values in the component's render logic (lines 48–74 of index.tsx). The CSS-in-JS styles are generated in components/cascader/style/index.ts.

Summary

• Define hierarchical data using the options prop with label, value, and optional children fields according to BaseOptionType.
• Enable advanced features by setting showSearch for keyword filtering and multiple for checkbox selection via the useCheckable hook.
• Customize the UI using popupRender to inject headers or footers, or use Cascader.Panel for standalone panel rendering.
• Leverage automatic integration with Ant Design's Form system, RTL support, and theme context through FormItemInputContext and ConfigProvider.

Frequently Asked Questions

How do I enable search functionality in the Cascader component?

Set the showSearch prop to true on the Cascader component. This activates the default search implementation defined in components/cascader/index.tsx (lines 15–35), which filters options across all levels based on user input. You can also provide a custom SearchConfig object to showSearch to define custom filtering logic or search field names.

What is the difference between Cascader and Cascader.Panel?

Cascader is the full component that includes an input trigger and dropdown behavior, implemented in components/cascader/index.tsx. Cascader.Panel, exported from the same package and defined in components/cascader/Panel.tsx, renders only the cascaded selection UI without the input trigger or dropdown logic. Use Cascader.Panel when you need to embed the selection interface directly into a page layout or custom container.

How does the Cascader component handle multiple selection?

When you set the multiple prop to true, the component invokes the useCheckable hook (lines 65–66 of components/cascader/index.tsx). This hook adds a checkable flag to the panel configuration, causing the underlying @rc-component/cascader to render checkboxes for each option. Users can then select multiple leaf nodes, and the component returns an array of value arrays representing the selected paths.

Can I customize the appearance of the Cascader dropdown?

Yes, you can customize the dropdown using the popupRender prop to wrap the menu with additional elements like headers or footers. For more advanced customization, use the variant, bordered, size, and status props, which are merged with Ant Design's global context values (lines 48–74 of components/cascader/index.tsx). For complete visual overrides, you can also use Cascader.Panel and wrap it in your own styled container.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}