Utility Actions

General-purpose actions for common operations.

set_loading

Sets a loading state flag.

Syntax

json

{
  "type": "set_loading",
  "key": "saving",
  "value": true
}

Properties

Property	Type	Required	Description
`key`	string	Yes	Loading state identifier
`value`	boolean	Yes	Loading state value

Examples

Basic usage:

json

{
  "type": "Button",
  "text": "Save",
  "loading": "{{loading.saving}}",
  "events": {
    "on_click": [
      { "type": "set_loading", "key": "saving", "value": true },
      {
        "type": "call_api",
        "api": "saveData",
        "onComplete": [
          { "type": "set_loading", "key": "saving", "value": false }
        ]
      }
    ]
  }
}

Loading overlay:

json

{
  "type": "Conditional",
  "conditions": [
    {
      "when": "{{loading.pageLoading}}",
      "render": {
        "type": "LoadingOverlay",
        "message": "Loading..."
      }
    }
  ]
}

Multiple loading states:

json

{
  "type": "Flex",
  "gap": "md",
  "children": [
    {
      "type": "Button",
      "text": "Save Draft",
      "loading": "{{loading.savingDraft}}",
      "disabled": "{{loading.publishing}}",
      "events": {
        "on_click": [
          { "type": "set_loading", "key": "savingDraft", "value": true },
          { "type": "call_api", "api": "saveDraft" },
          { "type": "set_loading", "key": "savingDraft", "value": false }
        ]
      }
    },
    {
      "type": "Button",
      "text": "Publish",
      "loading": "{{loading.publishing}}",
      "disabled": "{{loading.savingDraft}}",
      "events": {
        "on_click": [
          { "type": "set_loading", "key": "publishing", "value": true },
          { "type": "call_api", "api": "publish" },
          { "type": "set_loading", "key": "publishing", "value": false }
        ]
      }
    }
  ]
}

download

Downloads a file.

Syntax

json

{
  "type": "download",
  "url": "/api/export/data.csv",
  "filename": "export.csv"
}

Properties

Property	Type	Required	Description
`url`	string	Yes	File URL to download
`filename`	string	-	Suggested filename

Examples

Download file:

json

{
  "type": "Button",
  "text": "Download Report",
  "icon": "Download",
  "events": {
    "on_click": [
      { "type": "download", "url": "/api/reports/monthly.pdf", "filename": "report.pdf" }
    ]
  }
}

Dynamic download:

json

{
  "type": "Button",
  "text": "Export",
  "events": {
    "on_click": [
      {
        "type": "download",
        "url": "/api/export?format={{state.exportFormat}}&ids={{state.selectedIds}}",
        "filename": "export-{{$now | date:'YYYY-MM-DD'}}.{{state.exportFormat}}"
      }
    ]
  }
}

Download from API response:

json

{
  "type": "call_api",
  "api": "generateExport",
  "on_success": [
    { "type": "download", "url": "{{$response.downloadUrl}}", "filename": "{{$response.filename}}" }
  ]
}

copy

Copies text to clipboard.

Syntax

json

{
  "type": "copy",
  "text": "Text to copy"
}

Properties

Property	Type	Required	Description
`text`	string	Yes	Text to copy

Examples

Copy value:

json

{
  "type": "Button",
  "text": "Copy",
  "icon": "Copy",
  "events": {
    "on_click": [
      { "type": "copy", "text": "{{state.apiKey}}" },
      { "type": "show_toast", "message": "Copied!", "level": "success", "duration": 2000 }
    ]
  }
}

Copy link:

json

{
  "type": "Button",
  "text": "Share",
  "icon": "Share",
  "events": {
    "on_click": [
      { "type": "copy", "text": "{{$window.location.origin}}/share/{{state.item.id}}" },
      { "type": "show_toast", "message": "Link copied to clipboard", "level": "success" }
    ]
  }
}

Copy formatted text:

json

{
  "type": "copy",
  "text": "Name: {{state.user.name}}\nEmail: {{state.user.email}}\nPhone: {{state.user.phone}}"
}

open_url

Opens a URL in a new browser tab.

Syntax

json

{
  "type": "open_url",
  "url": "https://example.com"
}

Properties

Property	Type	Required	Description
`url`	string	Yes	URL to open
`target`	string	-	Target window (default: `_blank`)

Examples

Open external link:

json

{
  "type": "Button",
  "text": "Documentation",
  "icon": "ExternalLink",
  "events": {
    "on_click": [
      { "type": "open_url", "url": "https://docs.example.com" }
    ]
  }
}

Dynamic URL:

json

{
  "type": "Button",
  "text": "View Profile",
  "events": {
    "on_click": [
      { "type": "open_url", "url": "https://github.com/{{state.user.githubUsername}}" }
    ]
  }
}

Open in same tab:

json

{
  "type": "open_url",
  "url": "https://example.com",
  "target": "_self"
}

emit

Emits a custom event for inter-component communication.

Syntax

json

{
  "type": "emit",
  "event": "itemSelected",
  "data": { "id": "{{state.item.id}}" }
}

Properties

Property	Type	Required	Description
`event`	string	Yes	Event name
`data`	any	-	Event payload

Examples

Emit selection event:

json

{
  "type": "Button",
  "text": "Select",
  "events": {
    "on_click": [
      { "type": "emit", "event": "itemSelected", "data": "{{state.currentItem}}" }
    ]
  }
}

Listen for event:

json

{
  "events": {
    "onEvent:itemSelected": [
      { "type": "update_state", "path": "selectedItem", "value": "{{$event.data}}" }
    ]
  }
}

Parent-child communication:

json

{
  "type": "emit",
  "event": "formSubmitted",
  "data": {
    "formId": "contactForm",
    "values": "{{form.contactForm}}"
  }
}

Common Patterns

Loading with Error Handling

json

{
  "type": "Button",
  "text": "Submit",
  "loading": "{{loading.submit}}",
  "events": {
    "on_click": [
      { "type": "set_loading", "key": "submit", "value": true },
      {
        "type": "call_api",
        "api": "submit",
        "on_success": [
          { "type": "show_toast", "message": "Success!", "level": "success" }
        ],
        "on_error": [
          { "type": "show_toast", "message": "{{$error.message}}", "level": "error" }
        ],
        "onComplete": [
          { "type": "set_loading", "key": "submit", "value": false }
        ]
      }
    ]
  }
}

Copy with Feedback

json

{
  "type": "Flex",
  "align": "center",
  "gap": "sm",
  "children": [
    {
      "type": "Text",
      "text": "{{state.code}}",
      "className": "font-mono bg-muted px-2 py-1 rounded"
    },
    {
      "type": "Button",
      "variant": "ghost",
      "size": "sm",
      "icon": "{{state.copied ? 'Check' : 'Copy'}}",
      "events": {
        "on_click": [
          { "type": "copy", "text": "{{state.code}}" },
          { "type": "update_state", "path": "copied", "value": true },
          { "type": "show_toast", "message": "Copied!", "level": "success", "duration": 1500 }
        ]
      }
    }
  ]
}

Export Options

json

{
  "type": "Dropdown",
  "trigger": { "type": "Button", "text": "Export", "icon": "Download" },
  "items": [
    {
      "label": "CSV",
      "action": [{ "type": "download", "url": "/api/export?format=csv", "filename": "data.csv" }]
    },
    {
      "label": "Excel",
      "action": [{ "type": "download", "url": "/api/export?format=xlsx", "filename": "data.xlsx" }]
    },
    {
      "label": "PDF",
      "action": [{ "type": "download", "url": "/api/export?format=pdf", "filename": "data.pdf" }]
    }
  ]
}

Best Practices

Always reset loading states - Use onComplete to ensure loading stops
Show copy feedback - Confirm clipboard actions with toasts
Use meaningful event names - Make events self-documenting
Handle download errors - Wrap downloads in try/catch patterns
Validate URLs - Ensure URLs are valid before opening