Expressions

BubbleScript expressions describe Bubble’s dynamic values with typed sources and chained operations.

How an expression works

Most expressions start with a data source and then transform or inspect its value.

currentUser()
  .field("First name")
  .trimmed()
  .toUppercase()

Here, currentUser() returns a User, field("First name") returns text, and the remaining methods transform that text.

BubbleScript uses methods instead of JavaScript operators:

currentPageWidth().plus(20)
currentPageWidth().greaterThan(800)
currentUser()
  .loggedIn()
  .and(currentPageWidth().greaterThan(800))

Start from a Bubble value

Expression sources represent values available in the current Bubble context. For example:

currentUser()
currentDateTime()
currentPageWidth()
currentPageThing()
currentCellThing()
element("Email input")
search("Task")
option("Task Status", "Complete")
urlParameter("project")

Not every source is available everywhere. For example, element values belong to frontend contexts, while workflow parameters belong inside workflows.

Read fields

Use field(...) to follow data stored on a Bubble record.

currentUser().field("First name")
currentPageThing().field("Status")
currentPageThing()
  .field("Owner")
  .field("First name")

The generated app types let the agent use valid fields for the current record type.

Read element values

element(...) refers to another element in the current UI scope.

element("Email input").value()
element("Save button").isVisible()
element("Task group")
  .groupData()
  .field("Title")

The methods depend on the element type. An input provides a value, a group provides its data and a repeating group provides a list.

Build text

Use staticText(...) for fixed text and dynamicText(...) when a value changes at runtime.

staticText("Save changes")

dynamicText(
  "Welcome, ",
  currentUser().field("First name"),
  "!",
)

Dynamic parts must produce a printable value. A record or list normally needs to be reduced to a field, count or formatted value first.

Compare values and build conditions

Comparison methods return conditions that can control elements, workflows and privacy rules.

currentPageWidth().greaterThanOrEqual(1024)

currentPageThing()
  .field("Status")
  .equals(option("Task Status", "Complete"))

currentUser()
  .loggedIn()
  .and(
    currentPageThing()
      .field("Archived")
      .isFalse(),
  )

Stored yes/no fields use isTrue() or isFalse(). Predicates such as loggedIn() already return a condition.

Search for data

search(...) returns a typed list of Bubble records.

search("Task", {
  constraints: [
    {
      field: "Status",
      operator: "equals",
      value: option("Task Status", "To do"),
    },
  ],
  sort: [
    {
      field: "Due date",
      descending: false,
    },
  ],
}).limitTo(20)

The data type, field, operator and value must be compatible. The result can continue through list operations.

Work with lists

List methods reduce, select or transform a list.

search("Task").count()
search("Task").firstItem()
search("Task").limitTo(10)
search("Task")
  .field("Title")
  .uniqueItems()
  .joinedWith(", ")

The available operations depend on the item type. For example, number lists can be summed, while text lists can be joined.

Use workflow values

Workflows provide values such as parameters and results from earlier actions.

wfParam("Task")
previousStep(1)
workflowError()

The exact values depend on the workflow and its actions. The generated app types describe parameter names and result types.

Match the expected type

The final expression must return the value required by its destination.

• A condition must return yes/no.

• Text content must return text.

• A repeating-group data source must return a list of its content type.

• A workflow input must match the type accepted by that action.

A valid expression can still be wrong for the property where it is used. buildprint check reports the mismatch.

Preserve raw expressions

rawBubble(...) preserves an expression that does not yet have a typed BubbleScript form.

rawBubble({
  type: "FutureExpression",
  properties: {
    mode: "legacy",
  },
})

An agent should keep existing raw expressions unless the task requires changing them and their full meaning is understood.