Retool Cascader Component Upgrade: What's New and How to Migrate

Retool has released a new and improved version of the Cascader component, available now on Retool Cloud and for self-hosted organizations. The legacy Cascader is being deprecated, so if you're still using the old version, now is the time to plan your Retool Cascader component upgrade. This guide covers what changed, how to migrate your data, a known crash bug, and current limitations you should know about before shipping.

What's New in the Updated Retool Cascader Component

The new Cascader is a significant overhaul. Here's a quick summary of everything that changed:

• Manual or dynamic option lists: You can now manually add options or dynamically map them to existing query data — similar to how the Select component works.
• New dropdown UI: The component has been redesigned to look and behave like the Select component, giving it a cleaner, more consistent feel.
• Customizable labels: Options now support a configurable caption, color, and icon per label.
• Numeric values supported: Previously limited to strings, option values can now be numeric as well.
• New valuePath property: In addition to the selected value, you now have access to the full path of values leading to the selected option — useful for breadcrumb-style logic or multi-level filtering.
• Unique option values enforced: Like other modern Retool components, all option values must be unique. During a one-click upgrade, Retool will automatically append parent values to any duplicates to make them unique.

How to Upgrade Your Existing Cascader Component

If you have an existing Cascader component in your app, upgrading is straightforward for simple setups:

• Open the Inspector panel for your existing Cascader component.
• Click the Upgrade button that appears in the Inspector.
• Retool will automatically migrate the component to the new version, deduplicating option values where needed.

Important: If your legacy Cascader uses dynamic data — such as the output of a query — the one-click upgrade will not automatically transform your data structure. You'll need to do that manually.

How to Transform Your Data for the New Cascader

The new Cascader expects its data source to be an array of objects where each object includes a property pointing to its parent, similar to how Checkbox Group and Navigation components work. The component nests options by matching each item's parent value to another item's value.

For example, if you have a list of departments and roles, your data should look something like this:

• Each item has a value field (unique identifier).
• Each child item has a parentValue field that matches the value of its parent.
• Top-level items have no parentValue (or it is set to null).

If your query returns flat data, you'll need to write a JavaScript transformer to reshape it before passing it to the Cascader. Map over your query results and assign each item a value and a parentValue that correctly reflects the hierarchy you want to display.

Known Bug: Setting Parent Value Crashes the App

Several users in the Retool community have reported that when attempting to set the Parent Value field dynamically — using expressions like {{ item.department }} or {{ item?.department }} — the entire app crashes immediately.

This appears to be a confirmed bug, not a configuration error. If you're hitting this crash, here's what to do right now:

• Do not set the Parent Value field dynamically until a fix is released. Avoid using {{ item.department }} or similar expressions in that field for now.
• As a workaround, pre-process your data in a transformer so that the parent-child relationships are already resolved before the data reaches the Cascader. Pass in a fully structured array rather than relying on the component's Parent Value mapping to do the work.
• Watch the official Retool community thread for the patch announcement — Retool staff have confirmed they are tracking this issue.

Current Limitations to Know Before You Ship

The new Cascader is a step forward, but there are a few limitations worth knowing before you build around it:

• No multi-select support: You can only select a single leaf node. You cannot select multiple branches or intermediate parent nodes simultaneously. This is a frequently requested feature — especially for use cases like filters where a user might want to select "all sneakers" rather than drilling into a specific sub-category.
• No partial tree selection: Users are forced to navigate to a leaf node. Selecting a parent node without choosing a child is not currently supported.
• UX learning curve: The nested drill-down interaction is not immediately intuitive to all end users. If your app serves non-technical audiences, consider adding helper text or a label that explains how the component works.

Should You Upgrade Now?

If your Cascader uses a static option list, upgrading now is low-risk — use the one-click upgrade in the Inspector and test your app. If your Cascader uses dynamic query data, hold off on setting Parent Value dynamically until the crash bug is patched, and plan time to write a transformer to reshape your data. Either way, migration is inevitable — the legacy component is being deprecated, and the new version brings enough improvements to make the effort worthwhile.