> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reyapp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Logic, Actions, and Rules in Rey Explained

> Add logic to your Rey app — configure triggers, chain actions, and apply rules to create dynamic user experiences.

**Logic** is how your app responds to what users do. Attach logic to any component to define what happens when it's used — for example, when a button is tapped, a form is submitted, or a screen opens. In Rey, logic is built visually from two things:

* **Actions** — the individual steps Rey runs (save a row, navigate, show an alert, and so on).
* **Rules** — optional conditional if/then/else branches that decide *when* actions run.

No code required.

## How logic works

Select a component and open the **Logic** tab in the property toolbar above it to build its behavior. Every logic flow has:

* A **trigger** — the event that starts it (a button tap, a screen opening, a form submit).
* One or more **actions** — the steps that run in response.
* Optional **rules** — conditions that gate whether actions run.

Buttons are the most common target for logic, but you can attach logic to any interactive component.

## Triggers

A trigger is the event that fires your actions. Select a component and open the **Logic** tab in its property toolbar to choose from the available triggers for that component type:

<CardGroup cols={3}>
  <Card title="When tapped" icon="pointer">
    Fires when the user taps or clicks the component. The most common trigger for buttons, cards, and list items.
  </Card>

  <Card title="Screen load" icon="smartphone">
    Fires automatically when a screen opens. Use it to check a condition, set a user variable, or navigate elsewhere on entry.
  </Card>

  <Card title="Form submit" icon="send">
    Fires when the user submits a form. Rey validates required fields before running the actions.
  </Card>
</CardGroup>

## Action types

After choosing a trigger, pick an action from the dropdown. You can chain multiple actions together to build multi-step flows.

<AccordionGroup>
  <Accordion title="Go to screen — navigate to another screen">
    Send the user to another screen in your app. Choose the destination screen from the dropdown.

    **Optional: pass parameters.** If the destination screen needs data (for example, a detail screen that shows a specific record), map values to the screen's input parameters. For example, pass the `id` of the tapped list item so the detail screen knows which record to load.

    You can also navigate **Back** to return the user to the previous screen without specifying a destination.
  </Accordion>

  <Accordion title="Play audio — play a sound or track">
    Play an audio file when the action fires. Use it for sound effects on taps, background music on a screen load, or playing a track selected from a list.

    You can play a static uploaded file or bind the source to an `audio` field on the current entry — for example, playing the track a user tapped in a playlist.
  </Accordion>

  <Accordion title="Show paywall — prompt the user to subscribe">
    Show your app's paywall so the user can start a subscription or one-time purchase. Rey routes the paywall through your configured in-app purchase provider.

    Use this to gate premium screens, unlock exclusive content, or convert free users at the moment they hit a limit.
  </Accordion>

  <Accordion title="Show flash message — display a toast">
    Display a brief toast notification that disappears automatically. Best for non-critical feedback like `"Saved successfully"`, `"Link copied"`, or `"Please fill in all required fields"`.

    The message supports dynamic text — bind it to a data value if needed.
  </Accordion>

  <Accordion title="Open link — launch an external URL">
    Open a URL in the device's browser (or in an in-app webview). Enter a static URL or bind it to a data field — for example, open a `website_url` field value from the current entry.

    Use this for linking to external websites, downloadable files, or deep links into other apps.
  </Accordion>

  <Accordion title="Set user variable — store a value for the current user">
    Save a value to a **user variable** that persists across screens and app launches for the signed-in user. Use it to remember preferences (dark mode on/off), track onboarding state (completed the intro), or cache the last selected filter.

    Choose the variable, then set it to a static value, a form field's current value, or a value from the current entry.
  </Accordion>

  <Accordion title="Show review prompt — ask the user to rate your app">
    Trigger the native App Store or Google Play review prompt so the user can rate your app without leaving it. The OS controls how often the prompt can actually appear, so it's safe to call after positive moments (finishing a workout, completing a purchase).
  </Accordion>

  <Accordion title="Show notifications prompt — request push permission">
    Ask the user to allow push notifications. Trigger this after the user experiences value — for example, after they save their first item — to improve opt-in rates.

    Pair it with a **Set user variable** action to remember that you've already asked, so you don't prompt repeatedly.
  </Accordion>
</AccordionGroup>

## Applying rules

**Rules** let you wrap your actions in conditional if/then/else logic so they only run when certain criteria are met.

<Steps>
  <Step title="Open Apply rules">
    In the **Logic** tab of the property toolbar, click **Apply rules** to open the rules editor.
  </Step>

  <Step title="Define the If condition">
    Under **If**, click **Add condition** and choose a **data field** or **app state variable**, select a **comparison operator** (equals, does not equal, is greater than, contains, is empty, etc.), and enter or bind the **comparison value**.
  </Step>

  <Step title="Set the Then branch">
    Choose what happens when the condition is met — either **Do nothing** or an action to run.
  </Step>

  <Step title="Set the Else branch (optional)">
    Choose what happens when the condition is *not* met — for example, show an error toast if validation fails.
  </Step>

  <Step title="Add more branches (optional)">
    Click **Add branch** to add more conditions for complex flows.
  </Step>
</Steps>

<Info>
  Conditions can reference form field values, database fields, the current user's profile fields, screen parameters, or device state (such as whether the user is logged in). This lets you create branching logic entirely without code.
</Info>

## Chaining multiple actions

A single trigger can run as many actions as you need — they execute in order from top to bottom.

To chain actions:

1. Add your first action and configure it.
2. Click **+ Add action** below it to add the next step.
3. Drag actions up or down by their handle to reorder them.
4. Continue adding actions until the sequence is complete.

<Note>
  Actions run sequentially. Each action waits for the previous one to complete before starting. If an action encounters an error (for example, a required field is empty), subsequent actions in the chain do not run.
</Note>

## Example: a "Start free trial" button

Here's a complete, real-world flow that gates a premium screen behind a paywall and confirms the outcome — illustrating triggers, chained actions, and rules working together.

<Steps>
  <Step title="Set the trigger">
    Select the **Start free trial** button on your upsell screen. Open the **Logic** tab in the property toolbar and set the trigger to **When tapped**.
  </Step>

  <Step title="Action 1 — Show the paywall">
    Add a **Show paywall** action. Rey opens your configured in-app purchase sheet so the user can start a subscription.
  </Step>

  <Step title="Action 2 — Confirm with a flash message">
    Add a **Show flash message** action with the text `"You're in! Welcome to Pro."` This reassures the user after a successful purchase.
  </Step>

  <Step title="Action 3 — Go to the Pro home screen">
    Add a **Go to screen** action and set the destination to your **Pro Home** screen so the user lands directly on the paid experience.
  </Step>
</Steps>

<Tip>
  To avoid showing the paywall to users who already subscribed, click **Apply rules** and add an **If** condition on a `is_pro` user variable: only run **Show paywall** when `is_pro` is `false`. Set the **Else** branch to **Go to screen → Pro Home** directly. This is a clean pattern for gating premium content without duplicate flows.
</Tip>