show-alert

The action.show-alert provides a way to notify users about important information in your app, you can choose to show the alert as a toast for lightweight updates, or a modal for important messages. Alerts can be customized with styling, icons, and interactive elements, allowing you to tailor them to different scenarios.

The action.show-alert is considered a background action, meaning it can run automatically or silently without interrupting the current flow. Background actions typically occur behind the scenes, such as syncing data, saving changes, uploading files, or refreshing content.

In most cases, show-alert is configured to run in response to an event such as onPress, onFocus, onLoad, or onRefresh.

The alert may not always be triggered directly by the user. Instead, it can be triggered automatically after another action completes. For example, when a user submits a form, the app might attempt to save the data in the background, and if that save fails, action.show-alert is triggered to notify the user of the error.

Example use cases include:

• Error handling: Display a retry prompt when a payment fails.

• Login feedback: Highlight invalid credentials or missing permissions.

• Critical confirmations: Require approval before deleting a record or submitting an expense.

• Auto-dismiss functionality for non-critical notifications.

Configuration options

Some properties are common to all components, see Common component properties for a list and their configuration options.

Core Structure
title	The main heading text displayed at the top of the alert. It should be concise and clearly state the purpose of the message.
presentAs	Specifies how the alert is presented to the user. Options include: toast (default): For brief, lightweight notifications. modal: For important messages that require attention and may include additional information. Modal alerts are more disruptive since they block the UI and are typically used for critical information.

Other options
action	Interactive buttons or controls displayed within the alert let users respond or take specific actions. Use IntelliSense to see the list of available actions.
description	The detailed message content that explains the alert’s purpose, provides instructions, or delivers additional information to the user.
dismiss	Configures how users can dismiss the alert. You can enable a gesture dismissal and set an automatic dismissal time. autoAfter - specify the number of seconds after which the alert is automatically dismissed. Has no effect when dismiss is disabled. isEnabled - When set to true (default), allowing manual dismissal by swiping down. When set to false, the alert cannot be dismissed manually.
group	Grouping allows you to manage multiple alerts under a shared identifier. This ensures that only one alert from a group is visible at a time, preventing alert overload and improving the user experience. id - Identifier for the alert group. Only one alert per group can be visible at a time. If a new alert with the same group ID is triggered while another is active, it will be skipped.
icon	The icon displayed alongside the alert content provides visual context and helps users recognize the alert’s type or purpose. The alert’s style property determines the icon color. If no style is set, the default isWarning style is applied.
style	Visual styling options let you set the tone of the alert: isPositive (success/confirmation) isNegative (error) styling to convey the appropriate tone and urgency. isWarning (warning) styling is used by default.
subtitle	Secondary text that appears below the title, providing additional context or supplementary information.

Considerations

• The action.show-alert is only configurable in an event such as onPress , OnFocus, onLoad or onRefresh.

• When the show-alert is shown as a toast, tap on the toast to view additional details configured in the description property.

Examples and code snippets

Show-alert as a toast

Show alert as a toast

This example demonstrates an alert configured to display as a toast. It uses a negative style and a custom icon that supports the context of the message. The toast shows the title, subtitle, icon, and available actions at a glance. When the user taps on the toast, the full alert is revealed, including the description field, which can be configured as either static text or dynamically populated using an expression.

action-show-alert-toast.jigx

title: Alert - toast
type: jig.default

children:
  - type: component.list-item
    options:
      title: Show Alert toast
      rightElement:
        element: icon
        icon: arrow-button-circle-right
        # Configure the show-alert on the OnPress event.
        onPress:
          type: action.show-alert
          options:
            # Give the alert a title.
            title: This is an alert toast
            # Configure the type of alert to present on the screen.
            presentAs: toast
            # Add two actions buttons in the alert.
            actions:
              - type: action.go-back
                options:
                  title: go-back
              - type: action.go-to
                options:
                  title: Continue
                  linkTo: billing-form
                  # Style the second action button as secondary action.
                  style:
                    isSecondary: true
            # Add the details of the alert, which are displayed when the
            # toast alert is tapped.        
            description: This is an alert description
            # Select an icon in context with the alert.
            icon: alert
            # Style the alert depending on the severity  
            style:
              isNegative: true
            subtitle: Secondary text that appears below the title, providing additional context or supplementary information.

Show-alert as a modal

Show alert as a modal

This example demonstrates an alert configured to display as a modal. It uses a positive style and a custom icon that supports the context of the message. The modal shows the title, subtitle, description, icon, and available actions at a glance. The description field can be configured as either static text or dynamically populated using an expression.

action-show-alert-modal.jigx

title: Alert - modal
type: jig.default

children:
  - type: component.list-item
    options:
      title: Show Alert modal
      rightElement:
        element: icon
        icon: arrow-button-right
        color: color10
        # Configure the show-alert on the OnPress event.
        onPress:
          type: action.show-alert
          options:
            # Give the alert a title.
            title: This is an alert modal
            subtitle: Secondary text that appears below the title, providing additional context or supplementary information.
            # Configure the type of alert to present on the screen.
            presentAs: modal
            # Add two actions buttons in the alert.
            actions:
              - type: action.go-back
                options:
                  title: go-back
              - type: action.go-to
                options:
                  title: Continue
                  linkTo: billing-form
                  # Style the second action button as secondary action.
                  style:
                    isSecondary: true
            # Add the details of the alert, which are displayed in the modal.         
            description: This is a alert description and can include static text, inputs, dynamic data from expressions
            # Select an icon in context with the alert.
            icon: check
            # Style the alert depending on the severity 
            style:
              isPositive: true

Show-alert with actions

This example demonstrates how to configure an alert that evaluates a user's app subscription status. If the subscription has expired, an alert is triggered on the onLoad event in the index.jigx file, displaying a message with an action button that prompts the user to provide billing information and subscribe. The alert leverages the action.show-alert , with a condition set through the when property, reading from a custom subscription variable managed in Jigx Management. Importantly, the alert cannot be dismissed as the dismiss: isEnabled is set to false, compelling the user to either subscribe or exit the app.

Show alert with an action - modal

Show alert with an action - toast

index.jigx

name: online-marketplace
title: online-marketplace
category: health
description: Collection of sellers
icon: farmers-market-kiosk
color: color2

onLoad:
  # Alert the user if their subscriotion has expired.
  type: action.show-alert
  # Evaluate if the user subscription has expired or not, 
  # using the custom variables in Jigx Management.
  when: [email protected] = "Expired"
  options:
    title: Your Trial Has Expired
    description: Complete your billing details to subscribe.
    # Modal presentation style (overlays the current screen).
    # Change it to a modal.
    presentAs: toast
    icon: bill-cross-money-paper
    # Disable the alert forces the user to take action either by subscribing,
    # or by closing the app
    dismiss:
      isEnabled: false
    # Visual styling to indicate this is a negative action.  
    style:
      isNegative: true
    # Add an action to the alert for the user to subscribe and continue.  
    actions:
      - type: action.go-to
        options:
           # Visual styling to indicate this is a required action. 
          style:
            isDanger: true
          title: Subscribe
          linkTo: billing-form

tabs:
  Home:
    label: Home 
    jigId: products
    icon: home-apps-logo
  Shop:
    label: Shop online
    jigId: online-shop
    icon: farmers-market-kiosk

billing-form.jigx

Show-alert with styling onFocus

This example uses the onFocus event to notify (alert) the salesperson that the sales order requires the customer’s signature. The alert can be displayed as either a toast or a modal and is styled positively, as it serves as an informative reminder rather than an error.

action-show-alert-styling.jigx

title: Sales Order
type: jig.default

onFocus:
  # Display an alert modal to remind the sales person to get a signature.
  type: action.show-alert
  options:
    # Alert title displays below the icon.
    title: Reminder
    # Modal presentation style (overlays the current screen).
    # Change it to a toast.
    presentAs: modal
    subtitle: Customer signature is required
    # Icon provides a visual engagement
    icon: signature
    # Visual styling to indicate this is a informative/positive action
    style:
      isPositive: true

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1554224155-6726b3ff858f?w=500&auto=format&fit=crop&q=60

children:
  - type: component.form
    instanceId: sales-order-form
    options:
      isDiscardChangesAlertEnabled: true
      children:
        - type: component.section
          options:
            title: Customer Information
            children:
              - type: component.field-row
                options:
                  children:
                    - type: component.text-field
                      instanceId: customerFirstName
                      options:
                        label: First Name
                        isRequired: true
                    - type: component.text-field
                      instanceId: customerLastName
                      options:
                        label: Last Name
                        isRequired: true
              - type: component.email-field
                instanceId: customerEmail
                options:
                  label: Email
                  icon: email
                  isRequired: true
              - type: component.number-field
                instanceId: customerPhone
                options:
                  label: Phone Number
                  icon: phone
                  keyboardType: number-pad

        - type: component.section
          options:
            title: Order Details
            children:
              - type: component.dropdown
                instanceId: product
                options:
                  label: Select Product
                  isRequired: true
                  data: [email protected]
                  item:
                    type: component.dropdown-item
                    options:
                      title: [email protected]
                      value: [email protected]
              - type: component.field-row
                options:
                  children:
                    - type: component.number-field
                      instanceId: quantity
                      options:
                        label: Quantity
                        isRequired: true
                        keyboardType: number-pad
                    - type: component.number-field
                      instanceId: unitPrice
                      options:
                        label: Unit Price
                        isRequired: true
                        keyboardType: decimal-pad 

        - type: component.section
          options:
            icon:
              name: signature
            title: Customer Signature
            children:
              - type: component.signature-field
                instanceId: customerSignature
                options:
                  label: Sign Below
                  helperText: Please provide your signature to authorize this order

actions:
  - children:
      - type: action.execute-entity
        options:
          title: Submit Order
          provider: DATA_PROVIDER_DYNAMIC
          entity: default/sales-orders
          method: create
          data:
            customerFirstName: [email protected]
            customerLastName: [email protected]
            customerEmail: [email protected]
            customerPhone: [email protected]
            productId: [email protected]
            quantity: [email protected]
            unitPrice: [email protected]
            totalAmount: [email protected] * @ctx.components.unitPrice.state.value
            customerSignature: [email protected]
            createdAt: [email protected]

datasource

Show-alert with icons and styling onChange

This example uses the onChange event to alert the worker that the selected tool is unavailable. The alert can be displayed as a toast or a modal and is styled negatively, with a clear icon to reinforce that the selection is not allowed. When shown as a toast, the worker can tap it to view additional details.

Alert shown as a modal

Alert shown as a toast, tap for more details

action-show-alert-icon-styling.jigx

title: Tool Checkout
type: jig.default

onRefresh:
  type: action.reset-state
  options:
    state: [email protected]

onFocus:
  type: action.reset-state
  options:
    state: [email protected]

children:
  - type: component.list
    instanceId: toolshed
    options:
      data: [email protected]
      item:
        type: component.list-item
        options:
          title:
            text: [email protected]
            isBold: true
          subtitle:
            text: [email protected]
          leftElement:
            element: icon
            icon: [email protected]
            shape: circle
            type: contained
            color: color3
          rightElement:
            element: checkbox
            initialValue: false
            onChange:
              type: action.show-alert
              when: [email protected] = false
              options:
                title: [email protected] & " unavailable"
                description: Tool unavailable, select a different tool for the job."
                presentAs: modal
                style:
                  isNegative: true
                icon: road-sign-no-entry

datasource

Show-alert with automatic dismissal

This example illustrates how to display a warning alert to workers when specific jobs require PPE (Personal Protective Equipment). Each job is listed with an icon and a "Select" button. Upon selection, if the job necessitates PPE, a non-blocking toast alert appears detailing the required PPE items, reinforcing the importance of safety compliance. The alert is styled with a warning indication and is configured to automatically dismiss after three seconds, ensuring that the alert is noticeable without interrupting the workflow.

Dismiss alert after 3 seconds - Modal

Dismiss alert after 3 seconds - Toast

action-show-alert-dismissal.jigx

title: Today's Jobs
type: jig.default

children:
  - type: component.list
    options:
      data: [email protected]
      item:
        type: component.list-item
        options:
          title:
            text: [email protected]
            isBold: true
          subtitle: [email protected] & ' • ' & @ctx.current.item.time
          leftElement:
            element: icon
            icon: job-responsibility-bag-check
            color: color9
            type: contained
            shape: rounded
          rightElement:
            element: button
            title: Select
            onPress:
              type: action.action-list
              options:
                isSequential: true
                actions:
                  # Trigger an alert message
                  - type: action.show-alert
                    # Only show if the current item requires PPE.
                    when: [email protected] = true
                    options:
                      title: PPE required
                      description: ="Ensure you are wearing the correct PPE (Personal Protective Equipment) for this specific job. These include " & @ctx.current.item.ppeItems
                      # Display the alert as a toast (non-blocking banner-style alert)
                      # Change to modal if preferred.
                      presentAs: toast
                      # Automatically dismiss the toast after 3 seconds.
                      dismiss:
                        autoAfter: 3
                      style:
                       # Apply branding warning styling (usually yellow/orange).
                        isWarning: true
                      # Icon to visually reinforce the PPE requirement.
                      icon: hat-architect
                  - type: action.go-to
                    options:
                      linkTo: job-sheet
                      inputs:
                        job: [email protected]
                        location: [email protected]
                        time: [email protected]
                        PPE: [email protected]
                        ppeItems: [email protected]
                        priority: [email protected]

datasource

job-sheet.jigx

Show-alert with group id

Show-alert in a REST function