Forms - Forest Documentation

Action forms let you collect user input before executing an action. Forms can be static with fixed fields, or dynamic with fields that adapt based on context or user input.

Field properties

Fields are configurable using the following properties:

Property	Required	Type	Description
type	Yes	string	Field type: `Boolean`, `Date`, `Dateonly`, `Enum`, `Json`, `Number`, `NumberList`, `EnumList`, `String`, `StringList`, `File`, `FileList`, `Collection`
label	Yes	string	Label displayed to the user
id	No	string	Internal identifier. If not set, the label is used. Use this to access values in `context.formValues`
description	No	string	Help text displayed below the field
isRequired	No	boolean	Make the field required (default: false)
defaultValue	No	any	Default value pre-filled in the form
isReadOnly	No	boolean	Make the field read-only (default: false)
enumValues	Required for `Enum`	string[]	List of possible values when type is `Enum`
widget	No	string	UI widget to use (see widgets section below)

Basic form example

agent.customizeCollection('customers', collection => {
  collection.addAction('Charge credit card', {
    scope: 'Single',
    form: [
      {
        type: 'Number',
        label: 'Amount',
        description: 'Amount in USD (e.g., 42.50)',
        isRequired: true,
      },
      {
        type: 'String',
        label: 'Description',
        widget: 'TextArea',
      },
    ],
    execute: async (context, resultBuilder) => {
      const { Amount, Description } = context.formValues;
      const customer = await context.getRecord(['stripeId']);

      // Charge the credit card
      await stripe.charges.create({
        amount: Amount * 100,
        currency: 'usd',
        customer: customer.stripeId,
        description: Description,
      });

      return resultBuilder.success('Charged successfully!');
    },
  });
});

forest_agent.customize_collection('customers') do |collection|
  collection.add_action(
    'Charge credit card',
    BaseAction.new(
      scope: ActionScope::SINGLE,
      form: [
        {
          type: FieldType::NUMBER,
          label: 'Amount',
          description: 'Amount in USD (e.g., 42.50)',
          is_required: true
        },
        {
          type: FieldType::STRING,
          label: 'Description',
          widget: 'TextArea'
        }
      ]
    ) do |context, result_builder|
      form_values = context.form_values
      customer = context.get_record(['stripeId'])

      # Charge the credit card
      # ...

      result_builder.success('Charged successfully!')
    end
  )
end

@create_agent.collection :customers do |collection|
  collection.action 'Charge credit card', scope: :single do
    form do
      field :amount, type: :number, description: 'Amount in USD (e.g., 42.50)', is_required: true
      field :description, type: :string, widget: 'TextArea'
    end

    execute do
      customer = record(['stripeId'])
      amount = form_value(:amount)
      description = form_value(:description)

      # Charge the credit card
      # ...

      success 'Charged successfully!'
    end
  end
end

Field types

String

Text input for short strings.

{ type: 'String', label: 'Name' }

Use the TextArea widget for longer text:

{ type: 'String', label: 'Description', widget: 'TextArea' }

Number

Numeric input with optional constraints.

{ type: 'Number', label: 'Amount', defaultValue: 0 }

Boolean

Checkbox for true/false values.

{ type: 'Boolean', label: 'Send confirmation email' }

Date and Dateonly

Date picker for dates with or without time.

{ type: 'Date', label: 'Delivery date and time' }
{ type: 'Dateonly', label: 'Birth date' }

Enum

Dropdown with predefined options.

{
  type: 'Enum',
  label: 'Status',
  enumValues: ['pending', 'approved', 'rejected'],
  isRequired: true
}

Collection

Reference to a record from another collection.

{
  type: 'Collection',
  label: 'Assignee',
  collectionName: 'users',
  description: 'Select the user to assign this ticket to'
}

Collection reference widget on an action form

The value will be the primary key of the selected record (as an array for composite keys).

File and FileList

File upload fields.

{ type: 'File', label: 'Upload document' }
{ type: 'FileList', label: 'Upload attachments' }

Lists

Arrays of values.

{ type: 'StringList', label: 'Tags' }
{ type: 'NumberList', label: 'Scores' }
{ type: 'EnumList', label: 'Categories', enumValues: ['A', 'B', 'C'] }

Dynamic forms

Make forms reactive by using functions instead of static values. Functions receive the action context and access form values and selected records.

Dynamic required fields

Make a field required based on another field’s value:

form: [
  {
    type: 'Number',
    label: 'Amount',
    isRequired: true,
  },
  {
    type: 'String',
    label: 'Justification',
    description: 'Required for amounts over $1000',
    // Only required if amount > 1000
    isRequired: context => context.formValues.Amount > 1000,
  },
]

form: [
  {
    type: FieldType::NUMBER,
    label: 'Amount',
    is_required: true
  },
  {
    type: FieldType::STRING,
    label: 'Justification',
    description: 'Required for amounts over $1000',
    # Only required if amount > 1000
    is_required: ->(context) { context.form_values['Amount'] > 1000 }
  }
]

Conditional visibility

Show or hide fields based on conditions:

form: [
  {
    type: 'Boolean',
    label: 'Send email notification',
    id: 'sendEmail',
  },
  {
    type: 'String',
    label: 'Email address',
    // Only show if sendEmail is checked
    if: context => context.formValues.sendEmail === true,
  },
]

form: [
  {
    type: FieldType::BOOLEAN,
    label: 'Send email notification',
    id: 'sendEmail'
  },
  {
    type: FieldType::STRING,
    label: 'Email address',
    # Only show if sendEmail is checked
    if: ->(context) { context.form_values['sendEmail'] == true }
  }
]

Default values from record data

Pre-fill form with data from the selected record:

form: [
  {
    type: 'Number',
    label: 'Refund amount',
    // Default to the order total
    defaultValue: async context => {
      const order = await context.getRecord(['total']);
      return order.total;
    },
  },
]

form: [
  {
    type: FieldType::NUMBER,
    label: 'Refund amount',
    # Default to the order total
    default_value: ->(context) {
      order = context.get_record(['total'])
      order['total']
    }
  }
]

Dynamic enum values

Change dropdown options based on context:

form: [
  {
    type: 'Enum',
    label: 'Department',
    id: 'department',
    enumValues: ['Engineering', 'Sales', 'Support'],
  },
  {
    type: 'Enum',
    label: 'Team',
    // Teams depend on selected department
    enumValues: context => {
      const dept = context.formValues.department;
      if (dept === 'Engineering') return ['Backend', 'Frontend', 'DevOps'];
      if (dept === 'Sales') return ['Inbound', 'Outbound'];
      if (dept === 'Support') return ['L1', 'L2', 'L3'];
      return [];
    },
  },
]

form: [
  {
    type: FieldType::ENUM,
    label: 'Department',
    id: 'department',
    enum_values: ['Engineering', 'Sales', 'Support']
  },
  {
    type: FieldType::ENUM,
    label: 'Team',
    # Teams depend on selected department
    enum_values: ->(context) {
      dept = context.form_values['department']
      if dept == 'Engineering'
        ['Backend', 'Frontend', 'DevOps']
      elsif dept == 'Sales'
        ['Inbound', 'Outbound']
      elsif dept == 'Support'
        ['L1', 'L2', 'L3']
      else
        []
      end
    }
  }
]

Dynamic collection references

Change the target collection dynamically:

form: [
  {
    type: 'Enum',
    label: 'Entity type',
    id: 'entityType',
    enumValues: ['user', 'company'],
  },
  {
    type: 'Collection',
    label: 'Entity',
    // Collection name depends on entity type
    collectionName: context => context.formValues.entityType,
  },
]

form: [
  {
    type: FieldType::ENUM,
    label: 'Entity type',
    id: 'entityType',
    enum_values: ['user', 'company']
  },
  {
    type: FieldType::COLLECTION,
    label: 'Entity',
    # Collection name depends on entity type
    collection_name: ->(context) { context.form_values['entityType'] }
  }
]

Widgets

Widgets customize the UI appearance of fields. Here are the most common ones:

TextArea

Multi-line text input.

{ type: 'String', label: 'Notes', widget: 'TextArea' }

TextInput

One-line text input, the default widget for String fields.

{ type: 'String', label: 'Name', widget: 'TextInput' }

TextInputList

One-line text input to enter a list of string values.

{ type: 'StringList', label: 'Tags', widget: 'TextInputList' }

AddressAutocomplete

Text input with address autocomplete powered by the Google Maps API.

{
  type: 'String',
  label: 'Address',
  widget: 'AddressAutocomplete',
  placeholder: 'Type the address here'
}

AddressAutocomplete widget on an action form, empty state

AddressAutocomplete widget on an action form, with suggestions

Checkbox

Single checkbox for boolean values.

{ type: 'Boolean', label: 'Send a notification', widget: 'Checkbox' }

Alternative to Enum for dropdown selection.

{
  type: 'String',
  label: 'Priority',
  widget: 'Dropdown',
  options: ['Low', 'Medium', 'High']
}

RadioGroup

Radio buttons for single selection.

{
  type: 'Enum',
  label: 'Plan',
  widget: 'RadioGroup',
  enumValues: ['Free', 'Pro', 'Enterprise']
}

CheckboxGroup

Checkboxes for multiple selection.

{
  type: 'EnumList',
  label: 'Features',
  widget: 'CheckboxGroup',
  enumValues: ['API Access', 'Priority Support', 'Custom Domain']
}

DatePicker

Calendar widget for date selection.

{ type: 'Date', label: 'Appointment', widget: 'DatePicker' }

TimePicker

Input for entering a time value.

{ type: 'Time', label: 'Opening time', widget: 'TimePicker' }

ColorPicker

Color selection widget.

{ type: 'String', label: 'Brand color', widget: 'ColorPicker' }

FilePicker

File upload with preview.

{ type: 'File', label: 'Profile picture', widget: 'FilePicker' }

JsonEditor

JSON editor with syntax highlighting.

{ type: 'Json', label: 'Configuration', widget: 'JsonEditor' }

UserDropdown

Dropdown pre-filled with Forest users.

{ type: 'String', label: 'Assigned to', widget: 'UserDropdown' }

CurrencyInput

Number input with currency formatting.

{
  type: 'Number',
  label: 'Price',
  widget: 'CurrencyInput',
  options: { currency: 'USD' }
}

RichText

Rich text editor with formatting options.

{ type: 'String', label: 'Content', widget: 'RichText' }

Advanced patterns

Multi-step forms

Create wizard-like forms by conditionally showing sections:

form: [
  {
    type: 'Enum',
    label: 'Action type',
    id: 'actionType',
    enumValues: ['refund', 'replace', 'credit'],
  },
  // Refund fields
  {
    type: 'Number',
    label: 'Refund amount',
    if: context => context.formValues.actionType === 'refund',
  },
  // Replacement fields
  {
    type: 'Collection',
    label: 'Replacement product',
    collectionName: 'products',
    if: context => context.formValues.actionType === 'replace',
  },
  // Store credit fields
  {
    type: 'Number',
    label: 'Credit amount',
    if: context => context.formValues.actionType === 'credit',
  },
]

form: [
  {
    type: FieldType::ENUM,
    label: 'Action type',
    id: 'actionType',
    enum_values: ['refund', 'replace', 'credit']
  },
  # Refund fields
  {
    type: FieldType::NUMBER,
    label: 'Refund amount',
    if: ->(context) { context.form_values['actionType'] == 'refund' }
  },
  # Replacement fields
  {
    type: FieldType::COLLECTION,
    label: 'Replacement product',
    collection_name: 'products',
    if: ->(context) { context.form_values['actionType'] == 'replace' }
  },
  # Store credit fields
  {
    type: FieldType::NUMBER,
    label: 'Credit amount',
    if: ->(context) { context.form_values['actionType'] == 'credit' }
  }
]

Read-only fields for context

Show record data as read-only context:

form: [
  {
    type: 'String',
    label: 'Customer name',
    isReadOnly: true,
    defaultValue: async context => {
      const order = await context.getRecord(['customer:name']);
      return order.customer.name;
    },
  },
  {
    type: 'Number',
    label: 'Refund amount',
    isRequired: true,
  },
]

form: [
  {
    type: FieldType::STRING,
    label: 'Customer name',
    is_read_only: true,
    default_value: ->(context) {
      order = context.get_record(['customer:name'])
      order['customer']['name']
    }
  },
  {
    type: FieldType::NUMBER,
    label: 'Refund amount',
    is_required: true
  }
]

Validation with required fields

Combine conditions for complex validation:

{
  type: 'String',
  label: 'Manager approval',
  isRequired: context => {
    // Required if amount > 1000 and user is not admin
    return context.formValues.Amount > 1000 &&
           context.caller.role !== 'admin';
  },
}

{
  type: FieldType::STRING,
  label: 'Manager approval',
  is_required: ->(context) {
    # Required if amount > 1000 and user is not admin
    context.form_values['Amount'] > 1000 &&
      context.caller.role != 'admin'
  }
}

Accessing form values

In the execute handler, access form values from the context:

execute: async (context, resultBuilder) => {
  // Access by label
  const amount = context.formValues.Amount;

  // Access by id (if specified)
  const email = context.formValues['email'];

  // Access with spaces in label
  const firstName = context.formValues['First Name'];

  // Destructure multiple values
  const { Amount, Description } = context.formValues;
}

execute: ->(context, result_builder) {
  # Access by label
  amount = context.form_values['Amount']

  # Access by id (if specified)
  email = context.form_values['email']

  # Access with spaces in label
  first_name = context.form_values['First Name']

  # Multiple values
  amount = context.form_values['Amount']
  description = context.form_values['Description']
}

Layout components

Organize your fields with layout components, separators, rows, HTML blocks, and multi-page forms. Useful when a form has many fields and you want to break it into manageable chunks.

Common properties

Property	Required	Value	Description
type	Yes	`"Layout"`	Differentiates a layout element from a field
component	Yes	`"Separator"`, `"Row"`, `"HtmlBlock"`, `"Page"`	The layout component to render
if (Node.js) / if_condition (Ruby)	No	callable	Only display if the function returns true

Separator

A horizontal line between two form elements.

form: [
  { type: 'String', label: 'firstName' },
  { type: 'Layout', component: 'Separator' },
  { type: 'String', label: 'lastName' },
]

form: [
  { type: FieldType::STRING, label: 'firstName' },
  { type: FieldType::LAYOUT, component: 'Separator' },
  { type: FieldType::STRING, label: 'lastName' },
]

Form with a horizontal separator between two fields

HTML block

Render arbitrary HTML content inside a form, useful for instructions, embedded content, or rich formatting.

Property	Required	Value	Description
component	Yes	`"HtmlBlock"`	Enables this component
content	Yes	string or callable returning a string	HTML content to render

{
  type: 'Layout',
  component: 'HtmlBlock',
  content: ctx => `
    <div style="text-align:center;">
      <strong>Hi ${ctx.formValues.firstName} ${ctx.formValues.lastName}</strong>,
      here you can put <strong style="color: red;">all the HTML</strong> you want.
    </div>
  `,
}

{
  type: FieldType::LAYOUT,
  component: 'HtmlBlock',
  content: ->(context) {
    "<div style=\"text-align:center;\"><strong>Hi #{context.form_values['firstName']}</strong></div>"
  },
}

Row

Display two fields side by side on the same line.

A row is designed for exactly two fields. If if conditions hide one, the remaining field fills the line. If more than two are visible, only the first two render.

Property	Required	Value	Description
component	Yes	`"Row"`	Enables this component
fields	Yes	array of two fields	The two fields to display side by side. No nested layout elements allowed.

{
  type: 'Layout',
  component: 'Row',
  fields: [
    { label: 'gender', type: 'Enum', enumValues: ['M', 'F', 'other'] },
    {
      label: 'specify',
      type: 'String',
      if: ctx => ctx.formValues?.gender === 'other',
    },
  ],
}

{
  type: FieldType::LAYOUT,
  component: 'Row',
  fields: [
    { label: 'gender', type: FieldType::ENUM, enum_values: ['M', 'F', 'other'] },
    {
      label: 'specify',
      type: FieldType::STRING,
      if_condition: ->(context) { context.form_values['gender'] == 'other' },
    },
  ],
}

Multi-page form

Break a long form into multiple pages, with next/previous navigation.

When using pages, you must have only Page components at the root of your form, no mixing fields and pages at the root, no nesting pages inside pages.

Property	Required	Value	Description
component	Yes	`"Page"`	Enables this component
elements	Yes	array of fields and layout elements	Fields and layouts shown on this page
nextButtonLabel (Node.js) / next_button_label (Ruby)	No	string	Label for the next button
previousButtonLabel (Node.js) / previous_button_label (Ruby)	No	string	Label for the previous button

form: [
  {
    type: 'Layout',
    component: 'Page',
    nextButtonLabel: 'Go to address',
    elements: [
      { type: 'String', id: 'Firstname', label: 'First name' },
      { type: 'String', id: 'Lastname', label: 'Last name' },
      { type: 'Layout', component: 'Separator' },
      { type: 'Date', id: 'Birthdate', label: 'Birth date' },
    ],
  },
  {
    type: 'Layout',
    component: 'Page',
    previousButtonLabel: 'Go back to identity',
    elements: [
      {
        type: 'Layout',
        component: 'Row',
        fields: [
          { type: 'Number', id: 'StreetNumber', label: 'Street number' },
          { type: 'String', id: 'StreetName', label: 'Street name' },
        ],
      },
      { type: 'String', id: 'PostalCode', label: 'Postal code' },
      { type: 'String', id: 'City', label: 'City' },
      { type: 'String', id: 'Country', label: 'Country' },
    ],
  },
]

form: [
  {
    type: FieldType::LAYOUT,
    component: 'Page',
    next_button_label: 'Go to address',
    elements: [
      { type: FieldType::STRING, id: 'Firstname', label: 'First name' },
      { type: FieldType::STRING, id: 'Lastname', label: 'Last name' },
      { type: FieldType::LAYOUT, component: 'Separator' },
      { type: FieldType::DATE, id: 'Birthdate', label: 'Birth date' },
    ],
  },
  {
    type: FieldType::LAYOUT,
    component: 'Page',
    previous_button_label: 'Go back to identity',
    elements: [
      { type: FieldType::STRING, id: 'PostalCode', label: 'Postal code' },
      { type: FieldType::STRING, id: 'City', label: 'City' },
      { type: FieldType::STRING, id: 'Country', label: 'Country' },
    ],
  },
]

If every element on a page is hidden by if conditions, the page is automatically removed. To prevent this, add an unconditional HtmlBlock explaining why the page is empty.

​Field properties

​Basic form example

​Field types

​String

​Number

​Boolean

​Date and Dateonly

​Enum

​Collection

​File and FileList

​Lists

​Dynamic forms

​Dynamic required fields

​Conditional visibility

​Default values from record data

​Dynamic enum values

​Dynamic collection references

​Widgets

​TextArea

​TextInput

​TextInputList

​AddressAutocomplete

​Checkbox

​Dropdown

​RadioGroup

​CheckboxGroup

​DatePicker

​TimePicker

​ColorPicker

​FilePicker

​JsonEditor

​UserDropdown

​CurrencyInput

​RichText

​Advanced patterns

​Multi-step forms

​Read-only fields for context

​Validation with required fields

​Accessing form values

​Layout components

​Common properties

​Separator

​HTML block

​Row

​Multi-page form

Field properties

Basic form example

Field types

String

Number

Boolean

Date and Dateonly

Enum

Collection

File and FileList

Lists

Dynamic forms

Dynamic required fields

Conditional visibility

Default values from record data

Dynamic enum values

Dynamic collection references

Widgets

TextArea

TextInput

TextInputList

AddressAutocomplete

Checkbox

Dropdown

RadioGroup

CheckboxGroup

DatePicker

TimePicker

ColorPicker

FilePicker

JsonEditor

UserDropdown

CurrencyInput

RichText

Advanced patterns

Multi-step forms

Read-only fields for context

Validation with required fields

Accessing form values

Layout components

Common properties

Separator

HTML block

Row

Multi-page form