Controlled vs Uncontrolled

react-tree-multi-select supports both controlled and uncontrolled behavior for several internal states of the component (such as dropdown visibility, selection, expansion, etc.).
By default, the component operates in uncontrolled mode, meaning it manages its own internal state. For certain props, you may opt into controlled mode by providing the corresponding value prop.

When a state is controlled:

• The component derives its state exclusively from props
• Internal state updates are disabled for that feature
• You are responsible for updating the value in response to callbacks

This design allows you to:

• Keep simple cases easy with internal state
• Fully synchronize state with your application when needed
• Mix controlled and uncontrolled behavior across features

How it works

For most controllable features, the component follows this pattern:
Controlled - value
Uncontrolled - defaultValue

• If the controlled prop is provided, the component uses it as the source of truth.
• If it is not provided, the component initializes its internal state from the corresponding default* prop (if any) and manages the state internally afterward.
• Changes to default* props after the initial render are ignored.

This pattern applies consistently across different features (selection, expansion, etc.).

Selection

Controlled selection

When selectedIds is provided:

• The component does not update selection internally
• Selection is derived entirely from this prop
• You must update it in response to selection change callbacks

Uncontrolled selection

Use this when you want:

• Initial selection
• Internal state management afterward

Expansion

Controlled expansion

When expandedIds is provided:

• Expansion state is fully controlled by the parent
• The component never mutates expansion internally

Uncontrolled expansion

Use this when you want:

• Initial expansion
• Internal state management afterward

Dropdown Visibility

Controlled dropdown open

When isDropdownOpen is provided:

• The component derives the dropdown’s visibility state entirely from this prop
• Internal open/close state is disabled
• You should update isDropdownOpen in response to onDropdownToggle callback

This allows you to fully control when the dropdown is rendered or hidden and to synchronize its visibility with your application’s state, enabling custom behaviors such as toggling the dropdown from external controls or reacting to other UI events.

Uncontrolled dropdown open

When defaultIsDropdownOpen is provided:

• The component initializes its internal dropdown visibility state using this value
• The dropdown open/close state is managed internally afterward
• You do not need to handle onDropdownToggle unless you want to observe changes

This mode is useful when you want the dropdown to start open or closed but do not need to control its visibility from your application state.