Frontend events are the triggers that happen on a page, or on a view (see Key terms) in a native mobile app. A user often sets them off, by clicking a button or changing an input, but they can also fire on their own, like when a page finishes loading. They only trigger while the page is open.
This article walks through the two main groups of frontend events, element events and general events, with examples you can build yourself. For an overview of how frontend events differ from backend events, see Events.
Element events
The most basic triggers come from users interacting with an element (see Key terms). For example, a user clicks a Save button, which starts a set of actions that saves what they've typed to the database.
Element events include:
Event | When it triggers |
An element is clicked | The user clicks an element, such as a button or an icon. |
An input's value is changed | The value of an input form (see Key terms) is updated. |
An element has an error running a workflow | A workflow started by that element runs into an error. See catching errors. |
Some elements, including elements from plugins, add their own events to this list.
Reference: Element events
Example: button click
Let's start with one of the most common events an app can have: responding to a button click.
You can press Cmd + K on a Mac or Ctrl + K on Windows to quickly add a workflow to an element.
1. Add a button
Add a Button element to the page. In the example below, we've labeled it Click me.
2. Start the workflow
Right-click the button to open the context menu, and select Start/Edit workflow.
The right-click menu is the quickest way to create a workflow for an element.
3. Add actions
You'll be taken to the workflow canvas and the new workflow. Click the + icon to start adding actions.
The event is already set up for you, so you can go straight to choosing an action.
Example: input value changed
Next, let's set up a workflow that runs whenever the user changes the value in an input form. Bubble registers the change in one of two ways:
Input type | When the change registers |
Text-based elements | When the element loses focus |
Click-based elements, like dropdowns and calendars | When the user confirms their choice with a click |
1. Add an input
Add one of the elements from the input forms category. We're using a regular text input.
2. Start the workflow
Right-click the element and select Start/Edit workflow. Bubble recognizes the element type and sets the event to respond to the element's value changing.
This is the same right-click menu you use for a button.
3. Add actions
You'll be taken to the workflow canvas, where the new workflow is labeled after its event. Add the actions that should run when the value changes.
Bubble names the workflow after the event.
To save a value to the database whenever an input changes, you can also use auto-binding, which doesn't need a workflow.
Article section: Auto-binding
Example: catching errors
Sometimes a workflow runs into an error. For example, a user might try to log in with the wrong credentials. By default, Bubble tells them so in a standard browser message:
System errors will result in a standard error message like this in Chrome, but you can override that message by setting up an event to catch it.
The An element has an error running a workflow event lets you replace that message with your own. It's connected to the element that started the workflow. If a user enters the wrong password, the event belongs to the Log in button, not to the input, since the button is what started the workflow.
Let's use it to show an alert we can style however we want:
1. Add an alert
Add an Alert element (see Key terms) to the page and set it to appear at the top.
Enabling Position the alert at the top lets us stick the alert to the top of the screen regardless of scrolling position.
2. Add the event
In the Workflow tab, add a new workflow and pick the An element has an error running a workflow event. Then select the Log in button as the element.
The An element has an error running a workflow event triggers whenever a workflow triggered by an element (such as a button) fails to complete.
3. Show the alert
Add the Show message in an alert box action, and use Bubble's original error message as the text. The event now triggers every time a workflow started by the Log in button leads to an error.
The Show message in an alert box action displays the alert element with a customizable message.
Identifying and changing error messages
Identifying and changing error messages
In the example above, the alert shows the system-generated message from the Current workflow error's message data source.
The message operator returns the message Bubble would otherwise have displayed. The code operator identifies the error. If you want an action to run only on a certain error, you can use its Only when field to check the error code.
All of Bubble's built-in messages are stored in app texts, which you'll find in the Languages section of the Settings tab.
The code of each error message is shown in gray, all-caps text under its description, and you can edit the message itself on the right. Your edit replaces the message whether you show it with a workflow or in the default browser message.
General events
General events are triggered by something happening on the page that isn't directly tied to an element. They can be the result of something a user does, but they don't have to be.
Reference: General events
When the page is loaded or URL refreshed
The Page is loaded event triggers when the page loads, and when the URL is refreshed with the Go to page (see Key terms) action, such as when you add URL parameters. It's useful for anything that should happen as soon as a user arrives.
Since Go to page triggers the event even if the page doesn't technically reload, it can run more often than you intended. You can stop that with a condition. For example, you can save a value in a custom state (see Key terms) the first time the page loads, and check that value before running the event again.
The user is logged in or out
The User is logged in and User is logged out events trigger when a user's login status changes, which is useful for sending logged-out users to another page.
They also trigger on page load, based on the user's status. So if you send logged-out users to another page, that workflow runs as soon as a logged-out user tries to open the page.
When the Log the current user out of their other sessions or Log another user out of all their sessions action logs a user out on another device, the event may not trigger right away on that device. It triggers once the user takes another action on the page.
An unhandled error occurs
This event works like An element has an error running a workflow, but it applies more broadly. It catches errors anywhere on the page, regardless of which element caused them, if any. That's useful when you want to handle every error in one place, such as by showing the same message for all of them.
If both events could run for the same error, only An element has an error running a workflow runs.
If you set the event's Catch property to Any workflow error, Bubble stops displaying workflow error messages altogether. That can also hide messages that you and your users need to see.
When a condition is true
The Do when condition is true event uses a condition to check in real time whether something is true. It runs a workflow as soon as the expression returns yes.
Its Run this property decides how often that happens:
Option | What it does |
Only once | Triggers once per page load. The Go to page action doesn't reset this if the user stays on the same page. |
Every time | Triggers every time the condition is true. |
This event can cause performance issues if it triggers too often, so be mindful of the condition you use and the actions it runs.
At a set interval
The Do every 5 seconds event runs a workflow over and over while the page is open, and you can change the interval to suit your needs.
Article: Recurring workflows
Example: conditional expression
Let's use Do when condition is true to make something happen. When the user has entered both an email and a password, we'll animate the Sign up button to encourage them to click it.
Start by adding two inputs and a button. Set the Content format of the inputs to Email and Password. We don't just want the inputs to be filled in. We want them to be valid.
Then add a new workflow and pick Do when condition is true from the General category, and set up the event and its action:
The numbers match the table below.
Number | What's set up |
1 | We only need the animation to appear once, so we leave the Run this dropdown set to Only once. |
2 | The expression checks both inputs and uses the and operator, so both have to be valid. With or, one would be enough. |
3 | The Animate an element action animates the button. We picked the subtle Callout pulse animation. |
The expression needs to check four things:
Check | What it means |
| The input has to contain text. |
| The input has to contain a valid email address. |
| The input has to contain text. |
| Technically, all passwords are valid, but you can choose to require a certain password strength. |
Custom events
Custom events are the third kind of frontend event. They only run when another workflow triggers them, which saves you from repeating the same actions in several places.
Article: Custom events
Build frontend events with Bubble AI
You can ask the Bubble AI Agent to create a workflow for most of the events on this page. Select the element you're working with, describe what should happen, and then open the Workflow tab to see what it built.
The Agent supports a set list of frontend events: User is logged in, User is logged out, Page is loaded, Do every five seconds, Do when condition is true, An unhandled error occurs, and the events for an element being pressed, an input changing, and an element hitting an error. Custom events aren't on that list.
Here are a few prompts to try:
Create a workflow that runs when the user clicks the Log In button. It should log the user in using the values from the Email address and Password inputs on this page.
Create a workflow that shows an alert when the Log In button has an error running a workflow.
Create a workflow that runs when the user is logged out. It should send them to the login page.
Create a workflow that animates the Sign up button once when the Email and Password inputs are both valid.
Explain what this workflow does.
Article: Edit apps with AI
FAQ: Frontend events
Why does my User is logged out event run when the page loads?
Why does my User is logged out event run when the page loads?
The User is logged in and User is logged out events also trigger on page load, based on the user's status. That's why a redirect for logged-out users can run the moment they open the page.
What's the difference between An element has an error running a workflow and An unhandled error occurs?
What's the difference between An element has an error running a workflow and An unhandled error occurs?
The first catches errors from workflows started by one specific element. The second catches errors anywhere on the page. If both could run for the same error, only An element has an error running a workflow runs.
Can I show my own error message instead of the browser's?
Can I show my own error message instead of the browser's?
Yes. Catch the error with an event and show your own message, for example in an alert. See Example: catching errors.
How do I make Do when condition is true run only once?
How do I make Do when condition is true run only once?
Set its Run this property to Only once. It then triggers once per page load.
Can frontend events slow down my app?
Can frontend events slow down my app?
They can. Events that trigger often, like Do when condition is true and Do every 5 seconds, can affect performance and workload, depending on what they check and which actions they run.
Article section: Do when condition is true and conditions
Are frontend events secure?
Are frontend events secure?
Frontend workflows run at least partly on the user's device, so don't rely on them alone to protect anything. Base sensitive conditions on something the server can check, and protect your data with privacy rules.
Article section: Using conditions for security
Key terms
View: A view is the top-level element in a native mobile app, serving the same role that a page does in a web app.
Article: The view element (mobile)
Element: Elements are the objects that you place on the page as you design your app. There are many different types of elements, like texts, buttons, input fields, and calendars.
Article series: Elements
Input form: Input forms are elements that accept information from the user, such as a text field, a checkbox, a date picker, or a dropdown.
Article: Input forms
Alert: The Alert element is used to quickly flash a text message on the screen.
Reference: Alert
Go to page: The Go to page action is used to send the user to a page in your app. It's also used to change the Page thing or update URL parameters.
Reference: Go to page
Custom state: Custom states are variables that you can save on any element on the page, including the page itself. They let you store data temporarily that is reset when the page is reloaded.
Article: Custom states










