How to Use State Variables in Retool

In the left sidebar of the Retool editor, click the State tab (it shows a cylinder/database-like icon). Click + New State Variable. Give it a name like isModalOpen, selectedTab, or filterState. Set a Default value — for booleans use false, for strings use an empty string, for objects use {}. The state variable will appear in the panel and is immediately accessible in the app as {{ stateVarName.value }}.

Bind the state variable's current value to any component using {{ variableName.value }}. For example, to show a loading spinner only when isLoading is true, set the Spinner component's Hidden property to {{ !isLoading.value }}. To display a counter in a Text component, set the Text value to {{ counter.value }}. For a Select component, bind the Value property to {{ selectedTab.value }}.

1// In the Text component's value field:
2{{ `Current filter: ${filterState.value}` }}
3
4// In a Button's Disabled property:
5{{ isLoading.value }}
6
7// In a Table's filter/search field:
8{{ searchTerm.value }}

Create a JS Query and use await variableName.setValue(newValue) to update the state. The setValue() method is asynchronous — it returns a Promise. If you call setValue() without await and then immediately try to read variableName.value, you may get the old value. Always await the call when you need to use the new value in the same function.

1// JS Query: toggleModal
2// WRONG — do not read immediately without await
3isModalOpen.setValue(true);
4console.log(isModalOpen.value); // Still false!
5
6// CORRECT — await the Promise
7await isModalOpen.setValue(true);
8console.log(isModalOpen.value); // true
9
10// Toggle pattern
11await isModalOpen.setValue(!isModalOpen.value);

When your state variable holds an object, use setIn() to update a specific nested key without overwriting the entire object. The signature is variableName.setIn(['path', 'to', 'key'], newValue). This is much safer than reading the full object, spreading it, and calling setValue() — setIn() is atomic.

1// State variable 'formData' with default value: {}
2// { name: '', email: '', address: { city: '', zip: '' } }
3
4// Update top-level key
5await formData.setIn(['name'], textInput1.value);
6
7// Update nested key
8await formData.setIn(['address', 'city'], cityInput.value);
9
10// Read the full updated object
11console.log(formData.value);
12// { name: 'Alice', email: '', address: { city: 'New York', zip: '' } }

A common pattern is a toggle button that switches between two states. Create a boolean state variable named showAdvanced with a default of false. Add a Button component with the label bound to {{ showAdvanced.value ? 'Hide advanced options' : 'Show advanced options' }}. In the Button's Click event handler, create a JS Query that toggles the value.

1// JS Query: toggleAdvanced (triggered by Button click)
2await showAdvanced.setValue(!showAdvanced.value);
3
4// Button label (in Inspector → General → Label):
5{{ showAdvanced.value ? 'Hide advanced options' : 'Show advanced options' }}
6
7// Advanced section Container → Hidden property:
8{{ !showAdvanced.value }}

Use a state variable as an accumulator when building multi-step forms on a single page (using a Tabbed Container or a Stepped Container). Initialize the state variable formData with default {}. On each step's Next button, merge the current step's inputs into the state object using setIn() or a spread + setValue() pattern. On the final step, read formData.value and pass it to your submission query.

1// Step 1 Next button — JS Query: saveStep1
2await formData.setIn(['firstName'], firstNameInput.value);
3await formData.setIn(['lastName'], lastNameInput.value);
4await formData.setIn(['email'], emailInput.value);
5// Advance to next tab
6await tabbedContainer1.setCurrentTab(1);
7
8// Step 2 Next button — JS Query: saveStep2
9await formData.setIn(['company'], companyInput.value);
10await formData.setIn(['role'], roleSelect.value);
11await tabbedContainer1.setCurrentTab(2);
12
13// Final Submit button — JS Query: submitForm
14const payload = formData.value;
15await createUserRecord.trigger({
16  additionalScope: { userData: payload }
17});
18await formData.setValue({}); // Reset after submit