Custom states are variables you can save on any element on the page, including the page itself. They let you store data temporarily, which resets when the page reloads. This is useful when your app needs to remember something you don't need to keep permanently in the database.
Custom states aren't visible to your users directly, but they aren't a secure way to store sensitive data. Anything you put in a custom state, including its default value, can be read by the person using that device.
What custom states do
Custom states have a few defining properties:
They hold data only until the page reloads, at which point they reset to their default value (empty by default).
They're hidden from the user, but you can reference them in any dynamic expression.
They're stored client-side, which makes them faster than reading from and writing to the database.
They can hold any kind of data: basic types like text, numbers, and dates, option set options, and custom data types. They can also hold lists.
Each custom state belongs to an element, and you can create as many as you need on any element, including the page itself.
You can store any kind of Bubble data in a custom state, from a simple text value to a data type like a specific user or a shopping cart, anything you'd like your app to remember for the moment.
With a list, a custom state can track several pieces of data at once. For example, you can track which items a user selects in a repeating group by adding each one to the custom state's list.
Creating a custom state
Any element can hold a custom state, and it's up to you to decide which element is the most appropriate to store it on. There are two ways to create one.
With an action
1. Add the action
Add the Set state of an element action to a workflow.
2. Create the state
Pick the element (the page called my-page in the example), then click the + icon (2). Any existing custom states on that element will appear as an option. In this case there is no existing custom state. Click Create a new custom state to create on.
3. Set the name and type
Give the custom state a suitable name, and pick the data type it should hold.
Directly on an element
1. Select the element
Select the element that you want to add a custom state to. in this example, we've selected the page, called my-page. Then, click the custom state icon in the upper right corner of the element property editor.
2. Create the state
Clicking the icon opens up the custom states already stored on that element.
3. Set the name and type
Give the custom state a suitable name, and pick the data type it should hold.
Finding, editing, and deleting a custom state
You can use the element inspector to find, edit, and delete the custom states on an element. Click the information icon, as shown in the animation above.
A custom state's name updates everywhere in your app automatically, so it's safe to change. You can also change its data type or delete it, though both can create errors in the issue tracker if they leave a workflow or expression broken.
Assigning a value to a custom state
There are two ways to give a custom state a value:
1. Set a default value
Follow the steps in the guide above to open up the custom state editor from the element property inspector. In the example below we have a custom state called my-custom-state, of type text, holding the default value my-text
2. Use the Set state of an element action
Assign a value with the Set state of an element action. This works for any value, including dynamic ones.
Each time you assign a value to a state, its previous value is overwritten.
Custom states don't update automatically when database records are deleted. If you store a list of things in a custom state and one of those things is later deleted from the database, the list still shows the same item count, and the fields on the deleted record show up empty.
You can work around this by filtering the list in any expression that counts it, for example My element's custom state list:filtered [Creation Date is not empty]:count.
Other ways to learn
Video lessons
Video lessons