Component reference
Cascader
Choose a shipping destination through nested levels.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Choose a region to estimate the delivery window.
Width adapts to the available space
"use client";
import { useState } from "react";
import { Cascader, type PimoluCascaderOption } from "@pimolu/react";
const regions: PimoluCascaderOption[] = [
{
value: "europe",
label: "Europe",
children: [
{
value: "france",
label: "France",
children: [
{ value: "paris", label: "Paris" },
{ value: "lyon", label: "Lyon" },
{ value: "bordeaux", label: "Bordeaux" },
],
},
{
value: "germany",
label: "Germany",
children: [
{ value: "berlin", label: "Berlin" },
{ value: "munich", label: "Munich" },
],
},
{
value: "spain",
label: "Spain",
children: [
{ value: "madrid", label: "Madrid" },
{ value: "barcelona", label: "Barcelona" },
],
},
],
},
{
value: "north-america",
label: "North America",
children: [
{
value: "canada",
label: "Canada",
children: [
{ value: "montreal", label: "Montréal" },
{ value: "toronto", label: "Toronto" },
],
},
{
value: "united-states",
label: "United States",
children: [
{ value: "new-york", label: "New York" },
{ value: "san-francisco", label: "San Francisco" },
],
},
],
},
{
value: "asia",
label: "Asia",
children: [
{
value: "japan",
label: "Japan",
children: [
{ value: "tokyo", label: "Tokyo" },
{ value: "osaka", label: "Osaka" },
],
},
{
value: "singapore",
label: "Singapore",
children: [
{ value: "singapore-city", label: "Singapore" },
],
},
],
},
];
function ShippingExample() {
const [path, setPath] = useState<string[]>([]);
return (
<div className="grid gap-5 min-w-0">
<Cascader
label="Shipping destination"
placeholder="Country, then city"
options={regions}
value={path}
onChange={(nextPath) => setPath(nextPath)}
fullWidth
/>
<p className="max-w-prose leading-relaxed">
{
path.length === 0
? "Choose a region to estimate the delivery window."
: `Delivery to ${path
.slice(-1)
.join("")} is estimated at 2–4 business days.`
}
</p>
</div>
);
}
export function DemoExample() {
return (<ShippingExample />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Basic
Click a branch to expand it, then choose a leaf. The trigger shows the full path.
Controlled
value is the path from the root; onChange receives the path and its option.
States
Disabled, helper text, clearable, a pre-selected default and an empty data set.
Usage
Use Cascader for a path and TreeSelect when users need a broader tree view.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluCascaderOption
Type source| Name | Type | Default | Description |
|---|---|---|---|
valueRequired | string | — | Public Pimolu prop; see the source declaration for details. |
labelRequired | string | — | Visible label associated with the control. |
children | readonly PimoluCascaderOption[] | undefined | — | Public Pimolu prop; see the source declaration for details. |
disabled | boolean | undefined | false | Public Pimolu prop; see the source declaration for details. |
valueRequiredstringNo default extracted.
Public Pimolu prop; see the source declaration for details.
labelRequiredstringNo default extracted.
Visible label associated with the control.
childrenreadonly PimoluCascaderOption[] | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
disabledboolean | undefinedDefault: false
Public Pimolu prop; see the source declaration for details.
PimoluCascaderProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
id | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
optionsRequired | readonly PimoluCascaderOption[] | — | Public Pimolu prop; see the source declaration for details. |
value | readonly string[] | undefined | — | Controlled selection, from the root to the chosen option. |
defaultValue | readonly string[] | undefined | [] | Initial selection when uncontrolled. |
onChange | ((path: string[], option?: PimoluCascaderOption) => void) | undefined | — | Called with the new path and its option. A cleared selection reports an empty path and `undefined`. |
label | string | undefined | — | Visible label associated with the control. |
placeholder | string | undefined | "Select an option" | Public Pimolu prop; see the source declaration for details. |
helperText | string | undefined | — | Supporting text below the field. |
emptyMessage | string | undefined | "No options available." | Public Pimolu prop; see the source declaration for details. |
clearable | boolean | undefined | true | Public Pimolu prop; see the source declaration for details. |
disabled | boolean | undefined | false | Public Pimolu prop; see the source declaration for details. |
fullWidth | boolean | undefined | false | Use the available width of the parent. |
className | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
style | CSSProperties | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-label | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-labelledby | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
aria-describedby | string | undefined | — | Public Pimolu prop; see the source declaration for details. |
idstring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
optionsRequiredreadonly PimoluCascaderOption[]No default extracted.
Public Pimolu prop; see the source declaration for details.
valuereadonly string[] | undefinedNo default extracted.
Controlled selection, from the root to the chosen option.
defaultValuereadonly string[] | undefinedDefault: []
Initial selection when uncontrolled.
onChange((path: string[], option?: PimoluCascaderOption) => void) | undefinedNo default extracted.
Called with the new path and its option. A cleared selection reports an empty path and `undefined`.
labelstring | undefinedNo default extracted.
Visible label associated with the control.
placeholderstring | undefinedDefault: "Select an option"
Public Pimolu prop; see the source declaration for details.
helperTextstring | undefinedNo default extracted.
Supporting text below the field.
emptyMessagestring | undefinedDefault: "No options available."
Public Pimolu prop; see the source declaration for details.
clearableboolean | undefinedDefault: true
Public Pimolu prop; see the source declaration for details.
disabledboolean | undefinedDefault: false
Public Pimolu prop; see the source declaration for details.
fullWidthboolean | undefinedDefault: false
Use the available width of the parent.
classNamestring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
styleCSSProperties | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-labelstring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-labelledbystring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
aria-describedbystring | undefinedNo default extracted.
Public Pimolu prop; see the source declaration for details.
Accessibility
- Keep the hierarchy understandable and verify back navigation and disabled choices.