Skip to Content


React hook used to allow component to be controlled and uncontrolled modes, and provide control over it's internal state.

Most Chakra components utilize useControllableState for seamlessly managing regardless of whether it's controlled or uncontrolled.



The useControllableState hook returns the state and function that updates the state, just like React.useState does.

Basic usage#

Using this hook lets you use the initial state by default with an option to control the state via control props (using value).

Here's an example of an uncontrolled state.

Editable Example

Here's an example of an controlled state.

Editable Example

Contextual feedback and State updates#

This hook provides helpful error or warning messages when you switch between controlled or uncontrolled modes or when you attempt to update the defaultValue passed.


valueanyThe value to used in controlled mode
defaultValueanyThe initial value to be used, in uncontrolled mode
onChange(nextValue: any) => voidThe callback fired when the value changes
shouldUpdate(prev: any, next: any) => booleanThe condition to update the state
namestringThe component name this hook is used in
propsMapobjectA mapping for the props to give more contextual warning messages.
Edit this page