---
title: useControllableState
package: '@chakra-ui/hooks'
description: React hook to handle controlled vs uncontrolled component scenarios
---

React hook that allows any component handle
[controlled](https://reactjs.org/docs/forms.html#controlled-components) and
[uncontrolled](https://reactjs.org/docs/uncontrolled-components.html) modes, and
provide control over its internal state.

Most Chakra components use the `useControllableState` for seamlessly managing
both controlled or uncontrolled state scenarios.

## Import

```js
import { useControllableProp, useControllableState } from '@chakra-ui/react'
```

## useControllableProp

Given a prop value and state value, the `useControllableProp` hook is used to
determine whether a component is controlled or uncontrolled, and also returns
the computed value.

- It returns the prop value if the component is controlled
- It returns the state value if the component is uncontrolled

### Usage

```jsx live=false
const [isControlled, value] = useControllableProp(propValue, stateValue)
```

## useControllableState

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

```js live=false
const [value, setValue] = useControllableState(options)
```

### Usage

With `useControllableState`, you can pass an initial state (using
`defaultValue`) implying the component is uncontrolled, or you can pass a
controlled value (using `value`) implying the component is controlled.

Here's an example of an uncontrolled state.

```jsx
function Example() {
  const [value, setValue] = useControllableState({ defaultValue: 40 })
  return (
    <div>
      <Button onClick={() => setValue(value + 1)}>+</Button>
      <Box as='span' w='200px' mx='24px'>
        {value}
      </Box>
      <Button onClick={() => setValue(value - 1)}>-</Button>
    </div>
  )
}
```

Here's an example of a controlled state.

```jsx
function Example() {
  // you need a state and updater to change the value
  const [value, setValue] = React.useState(40)

  const [internalValue, setInternalValue] = useControllableState({
    value,
    onChange: setValue,
  })

  return (
    <div>
      <Button onClick={() => setInternalValue(value + 1)}>+</Button>
      <Box as='span' w='200px' mx='24px'>
        {internalValue}
      </Box>
      <Button onClick={() => setInternalValue(value - 1)}>-</Button>
    </div>
  )
}
```

### 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.**

## Props

<PropsTable of='useControllableState' />