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.

A GIF showing creating a quick retool app consisting of a form element comprising of a form with a text input field and a submit button. It also shows the user creating a JS query that expects name and marks parameter and prints them in the console.

⏭️ 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.

A GIF showing a user connecting a form's submit button to a retool JS query using button event handlers.

Let’s pass the name and marks to this query when we run it? I’ll share 2 ways to do so.

  1. 🎛️ 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.

An image showing two parameters named name and marks being added in additional Scope section of a JS query in retool.

A GIF showing a user binding a JS query to a form submit button and passing the required parameters by the query in additional scope.

Let’s now run and see the output in the debug console.

A GIF showing a user demonstrating the results of a JS query being triggered by a form's submit button click in retool.

  1. ✍️ 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?

An image showing triggering a retool JS query using run script feature and passing required parameters by the query in additional scope.

🔍 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.

0
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

Muneeb ul Hassan
Muneeb ul Hassan