For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/cascader.md.

Cascader

Select hierarchical options such as regions or categories.

Basic usage

children defines nested options. Expand a parent and select a leaf to commit the full path. disabled disables a whole branch.

basic.tsx
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [
  {
    value: 'design',
    label: 'Design',
    children: [
      { value: 'interface', label: 'Interface design' },
      { value: 'brand', label: 'Brand design' },
    ],
  },
  {
    value: 'engineering',
    label: 'Engineering',
    children: [
      { value: 'frontend', label: 'Frontend development' },
      { value: 'backend', label: 'Backend development' },
    ],
  },
  { value: 'archived', label: 'Archived category', disabled: true },
];

export function CascaderBasic() {
  return (
    <Form layout="vertical">
      <FormField label="Project category">
        <Cascader options={options} placeholder="Choose a category" />
      </FormField>
    </Form>
  );
}

Examples

Controlled path

value is an array of values from the root to the selected node. onChange also returns the full option path; clearing returns two empty arrays. Expanding a parent only changes the draft path. Returning to the first-level branch of a committed path restores its descendants.

Selected path: ["zhejiang","hangzhou","xihu"]
controlled.tsx
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      {
        value: 'hangzhou',
        label: 'Hangzhou',
        children: [
          { value: 'xihu', label: 'Xihu' },
          { value: 'yuhang', label: 'Yuhang' },
        ],
      },
      { value: 'ningbo', label: 'Ningbo', children: [{ value: 'haishu', label: 'Haishu' }] },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      { value: 'nanjing', label: 'Nanjing', children: [{ value: 'gulou', label: 'Gulou' }] },
      { value: 'suzhou', label: 'Suzhou', children: [{ value: 'gusu', label: 'Gusu' }] },
    ],
  },
  { value: 'archived', label: 'Archived region', disabled: true },
];

export function CascaderControlled() {
  const [value, setValue] = useState<string[]>(['zhejiang', 'hangzhou', 'xihu']);
  return (
    <Form layout="vertical">
      <FormField label="Delivery region">
        <Cascader options={regions} value={value} onChange={setValue} />
      </FormField>
      <Text role="status" tone="muted">
        Selected path: {JSON.stringify(value)}
      </Text>
    </Form>
  );
}

showSearch displays matching paths. Search covers supplied or already loaded options; it does not fetch remote results.

search.tsx
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      { value: 'hangzhou', label: 'Hangzhou' },
      { value: 'ningbo', label: 'Ningbo' },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      { value: 'nanjing', label: 'Nanjing' },
      { value: 'suzhou', label: 'Suzhou' },
    ],
  },
];

export function CascaderSearch() {
  return (
    <Form layout="vertical">
      <FormField label="Region">
        <Cascader options={regions} placeholder="Choose a region" showSearch />
      </FormField>
    </Form>
  );
}

Multiple selection

With multiple, value is a string[][] containing complete paths. Selecting the same path again removes it, and the popup stays open after selection.

Selected paths: 2
multiple.tsx
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      { value: 'hangzhou', label: 'Hangzhou' },
      { value: 'ningbo', label: 'Ningbo' },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      { value: 'nanjing', label: 'Nanjing' },
      { value: 'suzhou', label: 'Suzhou' },
    ],
  },
];

export function CascaderMultiple() {
  const [value, setValue] = useState<string[][]>([
    ['zhejiang', 'hangzhou'],
    ['jiangsu', 'nanjing'],
  ]);
  return (
    <Form layout="vertical">
      <FormField label="Region">
        <Cascader multiple options={regions} value={value} onChange={setValue} />
      </FormField>
      <Text role="status" tone="muted">
        Selected paths: {value.length}
      </Text>
    </Form>
  );
}

Single-line selections

tagWrap={false} keeps tags on one line and collapses overflow into +N. Use maxTagCount to limit the visible tags. Open the popup to review or change all selections.

single-line.tsx
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [
  {
    value: 'product',
    label: 'Product team',
    children: [
      { value: 'design', label: 'Product experience design' },
      { value: 'web', label: 'Frontend development' },
      { value: 'mobile', label: 'Mobile development' },
    ],
  },
];

export function CascaderSingleLine() {
  return (
    <Form layout="vertical">
      <FormField label="Product team">
        <Cascader
          multiple
          tagWrap={false}
          options={options}
          defaultValue={[
            ['product', 'design'],
            ['product', 'web'],
            ['product', 'mobile'],
          ]}
        />
      </FormField>
    </Form>
  );
}

Disabled and read-only

disabled prevents interaction. readOnly keeps the trigger focusable but prevents opening the popup, clearing or changing the value.

states.tsx
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [
  {
    value: 'design',
    label: 'Design',
    children: [
      { value: 'interface', label: 'Interface design' },
      { value: 'brand', label: 'Brand design' },
    ],
  },
  {
    value: 'engineering',
    label: 'Engineering',
    children: [
      { value: 'frontend', label: 'Frontend development' },
      { value: 'backend', label: 'Backend development' },
    ],
  },
  { value: 'archived', label: 'Archived category', disabled: true },
];

const value = ['design', 'interface'];

export function CascaderStates() {
  return (
    <Form layout="vertical">
      <FormField label="Disabled">
        <Cascader options={options} value={value} disabled />
      </FormField>
      <FormField label="Read-only">
        <Cascader options={options} value={value} readOnly />
      </FormField>
    </Form>
  );
}

Intermediate levels

changeOnSelect allows committing intermediate paths. Selecting a node with children keeps the popup open so selection can continue down the hierarchy.

Selected path: []
intermediate.tsx
import { Cascader, type CascaderOption, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      { value: 'hangzhou', label: 'Hangzhou' },
      { value: 'ningbo', label: 'Ningbo' },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      { value: 'nanjing', label: 'Nanjing' },
      { value: 'suzhou', label: 'Suzhou' },
    ],
  },
];

export function CascaderIntermediate() {
  const [value, setValue] = useState<string[]>([]);
  return (
    <Form layout="vertical">
      <FormField label="Region">
        <Cascader changeOnSelect options={regions} value={value} onChange={setValue} />
      </FormField>
      <Text role="status" tone="muted">
        Selected path: {JSON.stringify(value)}
      </Text>
    </Form>
  );
}

Lazy loading

Set isLeaf={false} on nodes without children; loadData returns their children on expansion. Keep options and loadData references stable, and use values unique across the entire tree.

Respect AbortSignal: changing the options, loader or cacheKey, or unmounting, cancels pending requests. Closing the popup does not. Use onLoadError for failure feedback; expand the node again to retry.

lazy.tsx
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const options: CascaderOption[] = [{ value: 'remote', label: 'Remote categories', isLeaf: false }];

function waitForChildren(signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    if (signal.aborted) {
      reject(new DOMException('Aborted', 'AbortError'));
      return;
    }
    const onAbort = () => {
      clearTimeout(timer);
      reject(new DOMException('Aborted', 'AbortError'));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener('abort', onAbort);
      resolve();
    }, 400);
    signal.addEventListener('abort', onAbort, { once: true });
  });
}

async function loadData(option: CascaderOption, signal: AbortSignal): Promise<CascaderOption[]> {
  await waitForChildren(signal);
  return [{ value: `${option.value}-child`, label: 'Loaded item', isLeaf: true }];
}

export function CascaderLazy() {
  return (
    <Form layout="vertical">
      <FormField label="Remote categories">
        <Cascader options={options} loadData={loadData} placeholder="Expand a category" />
      </FormField>
    </Form>
  );
}

Refreshing cached data

Update cacheKey when the data version changes to clear loaded children and cancel old requests. This example keeps the options and loader unchanged. Expand the category again after refreshing to load the new version.

Cache version: v1; Loaded version: Not loaded
cache.tsx
import { Button, Cascader, type CascaderOption, Flex, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useCallback, useRef, useState } from 'react';

const options: CascaderOption[] = [{ value: 'remote', label: 'Remote categories', isLeaf: false }];

function waitForChildren(signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    if (signal.aborted) {
      reject(new DOMException('Aborted', 'AbortError'));
      return;
    }
    const onAbort = () => {
      clearTimeout(timer);
      reject(new DOMException('Aborted', 'AbortError'));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener('abort', onAbort);
      resolve();
    }, 400);
    signal.addEventListener('abort', onAbort, { once: true });
  });
}

export function CascaderCache() {
  const [version, setVersion] = useState(1);
  const [loadedVersion, setLoadedVersion] = useState<number | null>(null);
  const versionRef = useRef(1);
  const loadData = useCallback(async (option: CascaderOption, signal: AbortSignal) => {
    const requestVersion = versionRef.current;
    await waitForChildren(signal);
    setLoadedVersion(requestVersion);
    return [
      { value: `${option.value}-child`, label: `Loaded item v${requestVersion}`, isLeaf: true },
    ];
  }, []);

  return (
    <Form layout="vertical">
      <FormField label="Remote categories">
        <Cascader
          options={options}
          loadData={loadData}
          cacheKey={version}
          placeholder="Expand a category"
        />
      </FormField>
      <Flex align="start">
        <Button
          onClick={() => {
            versionRef.current += 1;
            setVersion(versionRef.current);
            setLoadedVersion(null);
          }}
        >
          Refresh data
        </Button>
      </Flex>
      <Text role="status" tone="muted">
        Cache version: v{version}; Loaded version:{' '}
        {loadedVersion === null ? 'Not loaded' : `v${loadedVersion}`}
      </Text>
    </Form>
  );
}

popupWidth="auto" fits the content, and popupMaxWidth caps its width. Without a width override, the popup matches the trigger. See shared popup options for other popup settings.

popup.tsx
import { Cascader, type CascaderOption, Form, FormField } from '@ifhover/leaf-ui';

const regions: CascaderOption[] = [
  {
    value: 'zhejiang',
    label: 'Zhejiang',
    children: [
      { value: 'hangzhou', label: 'Hangzhou' },
      { value: 'ningbo', label: 'Ningbo' },
    ],
  },
  {
    value: 'jiangsu',
    label: 'Jiangsu',
    children: [
      { value: 'nanjing', label: 'Nanjing' },
      { value: 'suzhou', label: 'Suzhou' },
    ],
  },
];

export function CascaderPopup() {
  return (
    <Form layout="vertical">
      <FormField label="Region">
        <Cascader
          options={regions}
          placeholder="Choose a region"
          popupWidth="auto"
          popupMaxWidth={320}
        />
      </FormField>
    </Form>
  );
}

Set name to submit the path as a JSON array string; empty values submit an empty string. Uncontrolled values support form reset; reset controlled application state yourself. See Form for labels and errors, and ConfigProvider for built-in translations.

API

Cascader API

Other native button and aria-* attributes reach the trigger. className / style apply to the outer container.

PropertyTypeDefaultDescription
optionsreadonly CascaderOption[]RequiredHierarchical options
valuereadonly string[] | readonly (readonly string[])[]—Controlled path; the internal uncontrolled value is used when omitted.
defaultValuereadonly string[] | readonly (readonly string[])[][]Initial path for uncontrolled usage; native form reset is supported.
onChange((value: string[], selectedOptions: CascaderOption[]) => void) | ((value: string[][], selectedOptions: CascaderOption[][]) => void)—Return a path and its options in single mode or path and option arrays in multiple mode; called on selection, removal or clearing, with two empty arrays when cleared.
multiplefalse | truefalseEnable multiple selection; value and callback types change accordingly.
placeholderstringLocale defaultPlaceholder when empty; localized by ConfigProvider
size'sm' | 'md' | 'lg''md'Control size
status'error' | 'warning'—Validation appearance
disabledbooleanfalseDisable interaction.
readOnlyboolean—Lock the value against typing, selection, clearing and removal.
allowClearbooleantrueClearing returns two empty arrays
showSearchboolean—Enable search input.
changeOnSelectboolean—Allow selecting intermediate levels.
tagWrapbooleantrueAllow selected tags to wrap; false keeps one line and collapses overflow.
maxTagCountnumber | 'responsive'—Maximum visible tags; responsive collapses them to the available width.
displayRender(labels: ReactNode[], selectedOptions: CascaderOption[]) => ReactNode—Customize each selected path using its labels and options.
optionRender(option: CascaderOption) => ReactNode—Customize option content.
loadData(option: CascaderOption, signal: AbortSignal) => Promise<readonly CascaderOption[]>—Load children when expanding a node with isLeaf false and no supplied children; use signal to handle cancellation.
onLoadError(error: unknown, option: CascaderOption) => void—Called on loading failure, for retry feedback.
cacheKeystring | number—Changing the data version clears lazy caches and cancels stale requests.
openboolean—Controlled open state.
defaultOpenbooleanfalseInitial open state for uncontrolled usage.
onOpenChange(open: boolean) => void—Panel open-state changes
popupWidthnumber | string'trigger'Popup width; trigger matches the trigger, auto fits content (and may be narrower), numbers specify fixed pixels; CSS lengths are also supported.
popupMaxWidthnumber | string—Optional maximum popup width; no additional limit when unset, still bounded by the viewport.
namestring—Native FormData field name; nonempty values submit JSON paths and empty values submit an empty string.
formstring—ID of the associated native form.
requiredbooleanfalseRequire a non-empty value; compound controls validate once.
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—Placement relative to the trigger.
popupClassNamestring—Custom class for the popup.
popupStyleCSSProperties—Custom popup styles.
popupRender(content: React.ReactNode) => React.ReactNode—Wrap or extend popup content; retain the supplied content to preserve interaction.
getPopupContainer() => Element | DocumentFragment—Return a popup container, including a ShadowRoot.
refRef<HTMLButtonElement>—DOM reference

CascaderOption

The cascader option data structure, with child options organized through children.

PropertyTypeDefaultDescription
valuestringRequiredOption value; unique among siblings for static data and across the tree for lazy nodes to distinguish caches.
labelReactNodeRequiredVisible option content.
searchLabelstring—Plain text used to search a rich label.
isLeafboolean—Identify a leaf node explicitly, including in lazy data.
disabledbooleanfalseDisable this option and all descendants.
childrenreadonly CascaderOption[]—Child options.

CascaderFieldNames

Use mapCascaderOptions(records, fields) to convert records to CascaderOption[], then pass the result as options. CascaderFieldNames describes the mapping fields; it is not a Cascader prop.

import { mapCascaderOptions } from '@ifhover/leaf-ui';

const records = [{ id: 'design', name: 'Design', nodes: [{ id: 'interface', name: 'Interface design' }] }];
const options = mapCascaderOptions(records, {
  value: 'id',
  label: 'name',
  children: 'nodes',
});
PropertyTypeDefaultDescription
valuestring—Business-object field containing the option value.
labelstring—Business-object field containing the visible label.
childrenstring—Business-object field containing the child-node array.
disabledstring—Business-object field containing the disabled state.
isLeafstring—Business-object field containing the leaf marker.