Retool additionalScope: The Right Way to Pass Parameters to Queries

Let me guess, you're probably trying to pass a value — maybe a user ID, status, or form input — into a Retool query. You have already tried something like {{ someVar }}
but it's not working in a .trigger()
call. That's exactly where I was, until I discovered additionalScope
.
In this post, I’ll show you how to pass parameters properly when triggering queries in Retool — and how additionalScope
it can help you.
🧠 What Is additionalScope
in Retool?
If you are familiar with basic programming, it’s just like your normal passing parameters to function when you call it. If you come from a non-tech background, it’s just like ordering a custom t-shirt online. You don't just click "make shirt" - you specify size, color, design, and text. The printing service (function) takes all your specifications (parameters) and creates your unique product.
🚀 Let’s dive into a working example.
Let’s create a hypothetical scenario. Let’s say we have a form with an input field named Name
, with the regular submit
button. Now we want to manually trigger a JS query, but here is a twist, we want to pass a random number with that for some odd reason, let’s say grading ( BTW that would be unfair), when the user presses the submit button. How can we do that?
First, let’s quickly set up this app.
⏭️ Next Steps
1. We want to somehow run this query1
query when a user presses the submit button.
2. Somehow, we have to pass name
and marks
to this query, so query 1 can output it.
Let’s connect the submit button to this query so pressing the button somehow runs this query. Here’s how we can do that.
Let’s pass the name
and marks
to this query when we run it? I’ll share 2 ways to do so.
🎛️ First Method: Using Control Query
We’ll add the required variable names in the query in the query’s additionalScope section ( name
& marks
in this case. This will allow us to pass those parameters from the place we call it.
Let’s now run and see the output in the debug console.
✍️ Second Method: Using Run Script
We can change the event handler we attached to the submit handler to use Run Script
instead of control query
We did earlier, and paste in the following snippet, which is another way of doing the same thing.
query1.trigger( { additionalScope : { name : textInput1.value, marks : Math.random() } } )
Note: query1 is the name of the query we are trying to trigger/run, name
and marks
are the parameters we want to pass to query1 when we force it to execute?
🔍 Can We See the Parameters Passed to a Retool JS Query When Triggered?
Yep, once the query runs, we can expand it in the debug console to see exactly what parameters were passed in.
🏁 Wrapping Up
Passing parameters into queries in Retool doesn’t have to be messy, and additionalScope
is a seriously underrated feature that makes your struggle disappear.
Whether you're dealing with row actions, dynamic modals, or looped query executions, this technique lets you pass exactly what you need — nothing more, nothing less — at the moment you trigger your query.
Subscribe to my newsletter
Read articles from Muneeb ul Hassan directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
