# JSON Form Fields in Action Steps

> Applies to Versions: 2024.1+ Estimated Time: 15-20 minutes 1. Overview JSON Form Fields provide a quick and efficient way to create simple modal popup…

Source: https://www.fuuz.com/help/json-form-fields-actionform
Last updated: 2026-01-11

How-To Guides · Screens, dashboards and reports


Last updated January 11, 2026, 8:47 PM UTC

Article Type

Configuration / How-To

Audience

Application Designers, Developers, Partners

Module

Screen Designer

Applies to Versions

2024.1+

## 1. Overview

JSON Form Fields provide a quick and efficient way to create simple modal popup forms without designing a full screen. By defining form inputs using JSON configuration within action steps, you can rapidly build create and edit dialogs for your end users. This approach is ideal for straightforward data entry scenarios requiring only basic inputs in a single-column layout.

JSON Form Fields are typically used in action button configurations and table column menu features, allowing you to define popup forms directly within the action definition rather than creating separate screen designs.

**When to Use JSON Form Fields:** This approach is best suited for simple, single-record operations with a few basic inputs. For complex workflows, nested mutations, multi-step processes, or advanced layouts, use Screen Dialogues or dedicated form screens instead.

## 2. Prerequisites

- **Access Type:** App Admin or Developer
- **Permissions:** Screen design and deployment permissions
- **Knowledge:** Basic understanding of JSON syntax and Fuuz data models
- **Resources:** A screen with action buttons or table column menus configured

## 3. Choosing the Right Approach

Fuuz offers multiple ways to present forms to users. Understanding when to use each approach ensures optimal user experience and maintainability.

### Comparison: JSON Form Fields vs. Screen Dialogues

| Aspect | JSON Form Fields (Form Action) | Screen Dialogue |
| --- | --- | --- |
| **Best For** | Quick, simple forms with few fields | Complex workflows, advanced layouts, multi-step processes |
| **Layout** | Single column only | Full canvas control (multi-column, sections, tabs) |
| **Input Types** | Text, number, date, datetime, time, select, multiline, markdown | All input types plus charts, tables, visualizations, custom components |
| **Data Operations** | Simple mutations (single record create, edit, delete) | Complex mutations, nested records, mass creates, web flows |
| **Workflow Integration** | Limited to simple action steps | Full web flow integration, conditional logic, multi-step approvals |
| **Setup Time** | Minutes (JSON configuration) | Longer (full screen design) |
| **Reusability** | Embedded in action (less reusable) | Separate screen (highly reusable across multiple actions) |
| **Action Type** | `Form` | `Screen Dialogue` |

### Use JSON Form Fields When:

- You need only a few basic input fields (typically 1-6 fields)
- The operation is a simple single-record create, edit, or delete
- No complex validation logic or conditional field visibility is required
- You want rapid development without creating separate screen assets
- The form doesn't require charts, tables, or rich visualizations

### Use Screen Dialogues When:

- You need multi-column layouts or complex formatting
- The workflow involves web flows or multi-step processes
- You require supervisor signoffs or approval chains
- The form includes nested mutations or mass record operations
- You need conditional field visibility or complex validation
- The modal requires charts, tables, or other visualizations
- The form will be reused across multiple screens or actions

**Best Practice:** When using web flows for complex workflows and modals (such as supervisor signoffs), always use Screen Dialogues or separate screen designs. This provides the flexibility needed for proper workflow orchestration and error handling.

## 4. Procedure Steps

### Step 1: Navigate to the Screen Designer

1. Open the **Screen Designer** application
2. Open or create the screen where you want to add the popup form

### Step 2: Add an Action Trigger

Select or add an element that will trigger the popup form:

1. Add an **Action Button** to your screen, or
2. Configure a **Column Menu** action in a table, or
3. Use an existing action element

### Step 3: Configure the Form Action

1. Select the action element and open its properties panel
2. Add a new action step
3. Select the **"Form"** action type from the dropdown
4. Provide a **Name** for your form—this displays as the modal title to end users (e.g., "Create New Item", "Edit Record", "Add Comment")

### Step 4: Define Form Fields Using JSON

1. Locate the **Form Fields** section in the action configuration
2. Click the **four-way arrow icon** above the Form Fields section to open the full-screen editor
3. Define your form fields using the JSON array structure

**Basic Text Input Example:**

```
[
  {
    "name": "name",
    "description": "Enter the item name",
    "label": "Name",
    "type": "text",
    "dataPath": "name",
    "disabled": false,
    "validation": {
      "required": true
    },
    "defaultValue": "",
    "query": {
      "fields": ["name"]
    }
  }
]
```

### Step 5: Add Multiple Fields

Add additional field objects to the array, separated by commas:

```
[
  {
    "name": "name",
    "label": "Name",
    "type": "text",
    "dataPath": "name",
    "validation": { "required": true }
  },
  {
    "name": "description",
    "label": "Description",
    "type": "multiline",
    "dataPath": "description",
    "validation": { "required": false }
  },
  {
    "name": "quantity",
    "label": "Quantity",
    "type": "number",
    "dataPath": "quantity",
    "defaultValue": 1,
    "validation": { "required": true }
  },
  {
    "name": "dueDate",
    "label": "Due Date",
    "type": "date",
    "dataPath": "dueDate",
    "validation": { "required": false }
  }
]
```

### Step 6: Save and Test

1. Close the full-screen editor
2. Save your screen design
3. Deploy to test environment
4. Test the action to verify the popup form displays correctly

## 5. Configuration Reference

### Field Properties

| Property | Required | Description |
| --- | --- | --- |
| `name` | Yes | Unique identifier for the field; should match your data model field name |
| `label` | Yes | Display label shown to the user |
| `type` | Yes | Input type (see Available Field Types below) |
| `dataPath` | Yes | Path to the data model field to update |
| `description` | No | Help text displayed to users (often shown on hover or in help mode) |
| `disabled` | No | Set to `true` to make field read-only; default is `false` |
| `defaultValue` | No | Initial value for the field; user can change unless disabled |
| `validation` | No | Validation rules object (e.g., `{ "required": true }`) |
| `query` | No | Query configuration specifying which data model fields to include |

### Available Field Types

| Type | Description | Use Case |
| --- | --- | --- |
| `text` | Single-line text input | Names, titles, short text |
| `multiline` | Multi-line text area | Descriptions, notes, comments |
| `markdown` | Markdown-enabled text editor | Rich text content, formatted documentation |
| `number` | Numeric input | Quantities, amounts, counts |
| `date` | Date picker (date only) | Due dates, effective dates, birthdays |
| `datetime` | Date and time picker | Scheduled events, timestamps, appointments |
| `time` | Time picker (time only) | Shift times, daily schedules |
| `select` | Dropdown selection | Status, category, predefined options |
| `color` | Color picker with color wheel | Status colors, category colors, UI display colors |

### Color Input Example

The color input type provides a color wheel picker for users to select hex color values. This is useful for allowing end users to configure display colors for statuses, categories, or other UI elements.

```
{
  "name": "color",
  "description": "Color to be used in UI for display purposes",
  "label": "Color",
  "type": "color",
  "disabled": false,
  "dataPath": "color",
  "validation": {
    "required": false
  },
  "defaultValue": "#cccccc",
  "query": {
    "fields": ["color"]
  }
}
```

**Tip:** Color inputs store hex color codes (e.g., `#FF5733`). You can use these values directly in conditional formatting for table cells, status indicators, or any UI element that supports color styling. See the Table Column Conditional Formatting article for usage examples.

**Note:** Additional field type examples and configurations will be provided in future article revisions. For complex input requirements, consider using Screen Dialogues with full canvas-based screen design.

### Using Transforms in JSON Forms

You can incorporate dynamic behavior into JSON form fields using stringified transforms:

- **Pre-transforms in the action:** Apply transforms before the form displays to calculate default values or modify field configurations
- **Embedded transforms in form elements:** Include transforms directly within field properties for dynamic behavior based on context or access

## 6. Use Case Examples

### Example 1: Quick Create Form (Use JSON Form Fields)

**Scenario:** Add a "Create New Task" button to a task list table that opens a simple form with name, description, and due date.

**Why JSON Form:** Only 3 fields, single record creation, no complex workflow, no conditional logic.

```
[
  {
    "name": "name",
    "label": "Task Name",
    "type": "text",
    "dataPath": "name",
    "validation": { "required": true }
  },
  {
    "name": "description",
    "label": "Description",
    "type": "multiline",
    "dataPath": "description"
  },
  {
    "name": "dueDate",
    "label": "Due Date",
    "type": "date",
    "dataPath": "dueDate"
  }
]
```

### Example 2: Quick Edit from Table Row (Use JSON Form Fields)

**Scenario:** Column menu action to quickly edit a record's status and notes directly from the table.

**Why JSON Form:** Simple edit operation, 2 fields, no workflow integration needed.

### Example 3: Supervisor Approval (Use Screen Dialogue)

**Scenario:** An approval workflow that requires supervisor signature, comments, displays related documents, and triggers notifications.

**Why Screen Dialogue:** Requires web flow integration, displays additional data (documents), has conditional logic based on approval outcome, involves multiple related records.

### Example 4: Batch Record Creation (Use Screen Dialogue or Separate Screen)

**Scenario:** Import or create multiple inventory items at once with validation against existing records.

**Why Screen Dialogue/Separate Screen:** Mass create operations, nested mutations, complex validation requirements exceed modal scope.

### Example 5: Multi-Step Order Entry (Use Separate Screen)

**Scenario:** Order entry requiring customer selection, multiple line items, shipping configuration, and payment processing.

**Why Separate Screen:** Complexity exceeds what a modal should handle; requires tables for line items, multiple sections, and extensive workflow logic.

## 7. Troubleshooting

| Issue | Cause | Solution |
| --- | --- | --- |
| Form doesn't display | JSON syntax error in form fields configuration | Validate JSON structure; check for missing commas, brackets, or quotes |
| Data not saving | Incorrect `dataPath` or `name` doesn't match data model | Verify field names match your data model exactly (case-sensitive) |
| Field type not rendering correctly | Invalid or unsupported type value | Use supported types: text, multiline, markdown, number, date, datetime, time, select |
| Validation not working | Incorrect validation object structure | Ensure validation is an object: `"validation": { "required": true }` |
| Default value not appearing | Existing record data overrides default | Default values apply to new records; existing records use their current values |
| Need more complex layout | JSON Form Fields only support single-column layout | Use Screen Dialogue action type to open a fully designed screen as a modal |

## 8. Related Resources

- Screen Designer Overview
- Action Button Configuration
- Screen Dialogue Actions
- Web Flows and Workflow Integration
- Data Model Field Reference

## 9. Revision History

| Version | Date | Editor | Description |
| --- | --- | --- | --- |
| 1.0 | 2023-10-09 | Craig Scott | Initial Release - Text input example |
| 2.0 | 2025-01-11 | Craig Scott | Added comparison guide, field types reference, use cases, and Screen Dialogue guidance |

### Need more help?

Ask the Fuuz community, or open a ticket with Fuuz support.

[Ask the community](https://www.fuuz.com/community) [Open a ticket](https://support.fuuz.com/portal/en/newticket)

On this page

[1. Overview](#1-overview)

[2. Prerequisites](#2-prerequisites)

[3. Choosing the Right Approach](#3-choosing-the-right-approach)

[4. Procedure Steps](#4-procedure-steps)

[5. Configuration Reference](#5-configuration-reference)

[6. Use Case Examples](#6-use-case-examples)

[7. Troubleshooting](#7-troubleshooting)

[8. Related Resources](#8-related-resources)

[9. Revision History](#9-revision-history)