How To Use Custom Events In Bubble.io (Complete Guide)

2nd of January, 2024

Throughout this guide, you’ll learn everything you need to know about using custom events in Bubble.

Custom events are like reusable elements for workflows. If your page has multiple workflow triggers that run the same sequence of events, you’ll find your editor will quickly become bloated.

Custom events allow you to centralise workflow actions into a single event that’s universally accessible.

1. The benefits of using custom events

Before we walk through the process of creating a custom event, it’s important to first understand the key benefits they offer.

As your Bubble app starts to grow, pages often become bloated with workflows that power a wide range of features. In some cases, these workflows are often quite similar to each other.

If, for example, you had a workflow that created an account for a user whenever they click a ‘register’ button. On a single page in your app, you might have multiple registration buttons. This means that for each button, you’d have to recreate the exact same workflow.

This is one of the main problems that custom events solve. Custom events are like reusable elements – you build them once, then reference them anywhere.

Should you ever need to make changes to a workflow, you’ll only need to update the main custom event. This will automatically propagate those changes across every additional workflow where it’s referenced. It’ll save you hours of time when making changes to a workflow in the future.

On top of everything, custom events allow you to create a clean workflow structure. As a Bubble developer, being able to maintain your editor is essential to success. Custom events allow you to reduce the total count of workflows on any page.

Finally, the last main benefit of custom events is the impact they have on the sequence of workflow actions.

In Bubble, standard workflow actions don’t run sequentially. Instead, they run in parallel at the same time. If you have workflow actions that require a structured sequence, custom events give you control of the order of operation.

2. How to build a new custom event from scratch

If I open my Bubble editor, you’ll see that I’ve created a simple demo page that we’ll be using for our guide today. On this page, I’ve built what looks like a pretty standard user profile.

If I open my property editor on the page, you’ll see that I’ve set the content type to be a ‘user’. This is linked to my ‘user’ data type as it will allow me to send and store the data of a specific person when I preview the page.

When it comes to the elements on the page, you’ll also see that it’s broken down into two separate sections. On the left-hand side, we’re just displaying the details of a user, like their name, profile photo, and bio. Below this information, I also have a button that allows someone to follow this person.

On the right-hand side, I’ve added a repeating group element that displays a list of all the posts that have been published by the person whose profile we’re currently viewing.

Inside each post, I’m also displaying the details about the person who published this. Below those details is yet another button to follow this user.

Because there are two ‘follow’ buttons on one page, a user has more than one way to follow someone on their profile. That means that both of these buttons have their own individual workflow, although they do the exact same thing.

If we were to select the main ‘follow’ button and open the workflow tab, we’ll see that it contains two steps.

Within the first step, there’s an action that ‘makes changes to the current page user’. The change is that we’re updating this users list of people who follow them – adding to it the ‘current user’.

Then, within the second step of the workflow, we’re ‘making changes to the current user’, only this time, we’re adding the ‘current page user’ to the list of people that they follow.

Now, it’s important to note that the workflow powering the second ‘follow’ button looks identical to the first.

From here, what I’d like to do is add an additional step to both my workflows. This step will send an email to a user when someone follows their account. Because I need to replicate the same actions across two separate workflows, you’ll quickly see how time-consuming this will become.

We’ll select the first workflow on our page and add an event that sends an email. Within this email, we’ll type in a custom subject line and message. The message will read:

‘Hey ‘current page user’, you just received a new follower. Their name is ‘current user’s, name’.

After building out this step, we now need to replicate the entire process in the second ‘follow’ button workflow.

Thankfully, in Bubble, it’s possible to copy and paste workflow steps, however, there is still a faster way to duplicate a workflow. Using a custom event, it would remove the need to rebuild repetitive workflows entirely.

Another benefit to using a custom event is if I ever wanted to change the subject line of the email I’m sending. If I wanted to add an emoji within my subject line, I’d currently need to do this manually between all of my existing workflows. When doing this, there’s no guarantee that I’ll be consistent throughout the process.

As the admin of my app, I could accidentally add an emoji without the appropriate space after my text. This means there’s no definitive way to ensure my workflows are identical.

On top of everything, it’s going to be a pain in the butt to change this multiple times across several workflows. This is where we’re going to create our first custom event.

Instead of having to add all of these individual steps within the same workflow twice, what I’m going to do is create one custom workflow that will run this chain of events. Then, any time the follow button is clicked, I can reference that custom workflow. It’s truly as simple as that.

In order to create a custom event, we need to create a brand new workflow from scratch. If you scroll down to the bottom menu, you’ll see the option to create a new custom event.

When creating a custom event, the first thing you’ll need to do is give it a name. For our example today, I’ll be calling mine the ‘follow sequence’.

After giving your event a name, you can build out the remaining steps of your workflow. This is why I prefer to call these reusable workflows. In my opinion, the phrase ‘custom event’ sounds scary. It almost seems like we have too much control because things are custom.

Now, when it comes to building out our custom event, instead of rebuilding the entire workflow from scratch, I’m simply going to copy across the actions from my existing workflow.

After building out the workflow, I hope you’re ready, because this is my favorite part. When we open our existing workflows under each follow button, we can remove all of the original workflow steps.

Instead of having three steps, all I’m going to do is select the action that ‘triggers a custom event’. Now by default, I only have one custom event, so it’s going to select that automatically.

I bet right now you’re thinking, Lachlan, what about all the additional steps I need within my workflow?

Well, that’s where I’m going to hold you right up, because that is all we need to add to this workflow.

It’s done.

You can dust your hands off because it was truly that easy.

Whenever the follow button is clicked, It automatically triggers the custom event. This means it’s going to run all of the actions that sit within that workflow.

As impressive as this may seem, we’re not even done at this point. I’m yet to show you the best part.

3. Editing an existing custom event

What we’re going to do now is jump back over to our custom event and open up step 3 where I’m sending an email.

Now let’s say I want to change the copy of this email. If I update the emoji I’m displaying within the subject line, this change is automatically going to apply across every workflow that references my custom event.

This is the true benefit of using this feature. Instead of having to make this change across multiple workflows, I only had to update the core workflow. This is then automatically propagated throughout my app.

Now, at this point, that concludes about 80 percent of everything you need to know about custom events. So if you feel like you’ve got what you needed to learn, Von Voyage, it’s been fantastic.

But if you want to learn about the remaining 20%, which is going to take your custom events to the next level, I’d recommend sticking around.

So in my example today, I replaced all of my workflow steps and put them in one custom event. One thing I want to highlight, however, is that you don’t need to follow this exact same process.

What I mean, is that you’re not required to place all your workflow steps in one custom event.

What you could do is only build one step inside this.

And so what do I mean by that?

Let’s say if I were to open up my existing workflow when the follow button is clicked. For the sake of our tutorial today, let’s imagine that I only want to put step 3 here (which is where I’m sending my email within a custom event).

Now why would I want to do that? Let’s say that between these two workflows, not everything is going to be identical.

There might only be one step in the workflow that’s going to reference a similar workflow action that already exists. This action, of course, is going to send an email to a user.

What I can do is jump back to my workflow and quickly delete my custom event. Then what I’m going to do is add the two steps that already exist inside of this workflow.

So I’m just going to quickly copy these over. Now, after these steps run, I could trigger a custom event.

If I add one more step, I’ll reference my ‘follow sequence’ custom event. Inside of that event, I’ll only want to reference the action that sends an email. This means I can delete the first two steps that take place. After doing so, I’ll also update the name of the custom event to ‘follow email send’.

Now, within our traditional workflow, the two original steps will run as normal. Once these have been successfully executed, it’s going to trigger our custom event.

So to my point, you don’t need to put everything inside of a single custom event. You can simply add one step.

The main reason to do this would be if there’s a single workflow step that is referenced time and time again across several workflows. Storing that within a custom event will save you the time of having to rebuild it from scratch in each instance.

4. How custom events affect the sequence of workflow actions

Now something else that’s important to understand when using custom events, is the way in which all the steps inside of a workflow execute.

I mentioned this at the start of our tutorial today, but a lot of people don’t understand that workflow steps are not sequential.

When a workflow is triggered, Bubble automatically runs all of the actions at the exact same time.

When I initially started using Bubble, I was under the impression that step 1 would run, then step 2 would follow, and so on. As I just mentioned, however, every step is going to run at the exact same time. The only exception to this is if you use a custom event.

Let’s say if I were to move my custom event trigger into step two. This will now change the operation of this workflow.

All of the workflow steps before the custom event will continue to run in parallel. Once all of these steps are complete, Bubble will then run the step that references a custom event. Finally, after the custom event has finished running successfully, Bubble will then return to the original workflow sequence and run the remaining actions.

As you can see, custom events give control over the order of workflow operations.

5. How to send data within custom events using parameters

The last thing I wanted to share in this guide will completely change how you work inside Bubble.

As you already know, when you’re creating standard workflows in Bubble. It’s possible to reference data from previous steps. For example, if you were to ‘create a thing’ in step 1 of your workflow, within step 2, you could reference the ‘result of step 1’s thing…’.

When you’re working with custom events, however, it’s not possible to reference data from previous steps from the main workflow chain. This is because custom events sit separately in their own space.

Referencing data between workflow steps is an essential feature for any modern web app, so how can you create a workaround for this?

Thankfully, Bubble allows you to store and send data through parameters within your workflow action that triggers a custom event.

Now if all of that sounded like complete jargon, let me explain again in plain English.

In Bubble, a parameter is just a fancy way of saying that you’re going to send data to something.

Let’s say I open my custom event where I’m sending an email. I’m going to clear all the data in this workflow step where I reference the user I’ll send this to.

Now, if I wanted to reference an email address from my initial workflow, I can store that within a parameter field.

To create a parameter, I’ll need to open my custom event, then click the option to ‘add parameter’. If you’ve ever used URL parameters or page parameters inside of Bubble, this will look like a familiar experience.

The first thing I’ll need to do is give my paramater a name. I’ll call this ‘followed user’. This parameter will store the specific user that is being followed from my original workflow.

If I then re-open the original workflow that triggers my custom event, you’ll now see a field where I can store the data of a user that will be sent to my event. Within this field, I’ll just store the value of the ‘current page’s user’.

Whenever this workflow now runs, it’s going to send the data of a user to my custom event.

Back in my custom event, I’ll now have the option to reference the data sent through my parameter.

If I insert dynamic data, you’ll see we have the option to now reference the ‘followed user’. This is the user from my parameter.

When selecting this user, I’ll have the ability to pull any of the data fields that live within this data type. In my example today, I’d like to reference their email address.

Finally, the last thing I should note is that it’s possible to send data through multiple parameters within a custom event. You’re not just restricted to using one. This will allow you to send and store several data types at once.

And just like that, you now know everything about working with custom events in Bubble. As you can see, these are a powerful feature that allows you to build a more robust application.