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

# Props

> Learn about different types of properties used in triggers / actions

Properties are used in actions and triggers to collect information from the user. They are also displayed to the user for input. Each property renders as a labelled field in the step settings form; the previews below show exactly what the user sees.

## Basic Properties

These properties collect basic information from the user.

### Short Text

This property collects a short text input from the user.

Name \*

Enter your name

```typescript theme={null}
Property.ShortText({
  displayName: 'Name',
  description: 'Enter your name',
  required: true,
  defaultValue: 'John Doe',
  placeholder: 'Enter your name',
});
```

### Long Text

This property collects a long text input from the user.

Description

Enter a description

```typescript theme={null}
Property.LongText({
  displayName: 'Description',
  description: 'Enter a description',
  required: false,
});
```

### Rich Text

This property gives the user a formatting toolbar (bold, italic, underline, links, lists) and preserves `{{ variables }}` inserted from previous steps. Pair it with a sibling dropdown via `formatProperty` to let the user switch between **plain text** and **HTML**; the returned value is a plain string in the chosen format.

Body \*

B
I
U

•
1\.

Hi First name, thanks for reaching out — we'll reply shortly.

```typescript theme={null}
props: {
  body_type: Property.StaticDropdown({
    displayName: 'Body Type',
    required: true,
    defaultValue: 'plain_text',
    display: 'cards',
    options: {
      options: [
        { label: 'Plain text', value: 'plain_text', description: 'Simple', icon: 'text' },
        { label: 'HTML', value: 'html', description: 'Rich + styled', icon: 'code' },
      ],
    },
  }),
  body: Property.RichText({
    displayName: 'Body',
    description: 'Body of the email',
    required: true,
    // Name of the sibling dropdown whose value selects the editing mode.
    formatProperty: 'body_type',
  }),
}
```

> [!TIP]
>
> `formatProperty` maps the sibling value by convention: `plain_text` / `plain` / `text` → plain, `html` → rich HTML, `markdown` / `md` → markdown. Anything else falls back to plain.

### Checkbox

This property presents a toggle for the user to switch on or off.

Agree to Terms
Check this box to agree to the terms

```typescript theme={null}
Property.Checkbox({
  displayName: 'Agree to Terms',
  description: 'Check this box to agree to the terms',
  required: true,
  defaultValue: false,
});
```

You can also **reveal nested fields** only when the checkbox is on by listing their names in `reveals`. The revealed fields appear indented beneath the toggle.

Has attachmentOnly match emails with a file

```typescript theme={null}
props: {
  has_attachment: Property.Checkbox({
    displayName: 'Has attachment',
    description: 'Only match emails with a file',
    required: false,
    defaultValue: false,
    reveals: ['attachment_name'],
  }),
  attachment_name: Property.ShortText({
    displayName: 'Attachment name',
    required: false,
    placeholder: 'e.g. invoice.pdf',
  }),
}
```

### Markdown

This property displays a markdown snippet to the user, useful for documentation or instructions. It includes a `variant` option to style the markdown, using the `MarkdownVariant` enum:

* **BORDERLESS**: For a minimalistic, no-border layout.
* **INFO**: Displays informational messages.
* **WARNING**: Alerts the user to cautionary information.
* **TIP**: Highlights helpful tips or suggestions.

The default value for `variant` is **INFO**.

**Heads up**
Paste your webhook URL into the service to start receiving events.

```typescript theme={null}
Property.MarkDown({
    value: '## This is a markdown snippet',
    variant: MarkdownVariant.WARNING,
}),
```

> [!TIP]
>
> If you want to show a webhook url to the user, use `{{ webhookUrl }}` in the
> markdown snippet.

### DateTime

This property collects a date and time from the user.

Date and Time \*

2023-06-09 12:00

```typescript theme={null}
Property.DateTime({
  displayName: 'Date and Time',
  description: 'Select a date and time',
  required: true,
  defaultValue: '2023-06-09T12:00:00Z',
});
```

### Date Range

This property collects a relative or absolute time window. The user picks a preset (last 24 hours, 7 / 30 / 90 days, this month) or a **custom range** with explicit *after* / *before* dates. Set `display: 'dropdown'` to render the presets as a compact select (used inside the filter builder); omit it for pill buttons.

Date

```typescript theme={null}
Property.DateRange({
  displayName: 'Date',
  description: 'Limit results to a time window',
  required: false,
  display: 'dropdown',
});
```

The value is `{ preset, after?, before? }`. Resolve it to concrete ISO bounds inside `run()` with `dateRangeUtils.resolve`. Relative presets resolve against "now", so recurring flows roll the window forward:

```typescript theme={null}
import { dateRangeUtils } from '@activepieces/pieces-framework';

const { after, before } = dateRangeUtils.resolve(context.propsValue.date_range);
// after / before are ISO strings (or undefined for an open bound)
```

### Number

This property collects a numeric input from the user.

Quantity \*

0

```typescript theme={null}
Property.Number({
  displayName: 'Quantity',
  description: 'Enter a number',
  required: true,
});
```

Set `display: 'stepper'` with `min` / `max` / `step` to render a compact −/value/+ control for bounded numbers.

Max results

−

*

```typescript theme={null}
Property.Number({
  displayName: 'Max results',
  required: false,
  defaultValue: 10,
  display: 'stepper',
  min: 1,
  max: 500,
  step: 1,
});
```

### Static Dropdown

This property presents a dropdown menu with predefined options.

Country \*

United States

```typescript theme={null}
Property.StaticDropdown({
  displayName: 'Country',
  description: 'Select your country',
  required: true,
  options: {
    options: [
      {
        label: 'Option One',

        value: '1',
      },
      {
        label: 'Option Two',
        value: '2',
      },
    ],
  },
});
```

For a small set of choices, set `display: 'cards'` to render the options as selectable cards. Each option may carry an `icon` and a short `description`.

Body Type \*

```typescript theme={null}
Property.StaticDropdown({
  displayName: 'Body Type',
  required: true,
  defaultValue: 'plain_text',
  display: 'cards',
  options: {
    options: [
      { label: 'Plain text', value: 'plain_text', description: 'Simple', icon: 'text' },
      { label: 'HTML', value: 'html', description: 'Rich + styled', icon: 'code' },
    ],
  },
});
```

### Static Multiple Dropdown

This property presents a dropdown menu with multiple selection options.

Colors \*

Red ×
Blue ×

```typescript theme={null}
Property.StaticMultiSelectDropdown({
  displayName: 'Colors',
  description: 'Select one or more colors',
  required: true,
  options: {
    options: [
      {
        label: 'Red',
        value: 'red',
      },
      {
        label: 'Green',
        value: 'green',
      },
      {
        label: 'Blue',
        value: 'blue',
      },
    ],
  },
});
```

### JSON

This property collects JSON data from the user.

Data \*

\{
"key": "value",
"count": 3
}

```typescript theme={null}
Property.Json({
  displayName: 'Data',
  description: 'Enter JSON data',
  required: true,
  defaultValue: { key: 'value' },
});
```

### Dictionary

This property collects key-value pairs from the user.

Options \*

key1

value1

×

key2

value2

×

* Add item

```typescript theme={null}
Property.Object({
  displayName: 'Options',
  description: 'Enter key-value pairs',
  required: true,
  defaultValue: {
    key1: 'value1',
    key2: 'value2',
  },
});
```

### File

This property collects a file from the user, either by providing a URL or uploading a file.

File \*

Enter a URL or upload a file

```typescript theme={null}
Property.File({
  displayName: 'File',
  description: 'Upload a file',
  required: true,
});
```

### Color

This property collects a color from the user via a swatch and hex input.

Brand color

\#8142E3

```typescript theme={null}
Property.Color({
  displayName: 'Brand color',
  description: 'Pick a color',
  required: false,
});
```

### Array of Strings

This property collects an array of strings from the user.

Tags

tag1

×

tag2

×

* Add item

```typescript theme={null}
Property.Array({
  displayName: 'Tags',
  description: 'Enter tags',
  required: false,
  defaultValue: ['tag1', 'tag2'],
});
```

### Array of Fields

This property collects an array of objects from the user.

Fields

×

Field Name \*

e.g. email

Field Type \*

TEXT

* Add item

```typescript theme={null}
Property.Array({
  displayName: 'Fields',
  description: 'Enter fields',
  properties: {
    fieldName: Property.ShortText({
      displayName: 'Field Name',
      required: true,
    }),
    fieldType: Property.StaticDropdown({
      displayName: 'Field Type',
      required: true,
      options: {
        options: [
          { label: 'TEXT', value: 'TEXT' },
          { label: 'NUMBER', value: 'NUMBER' },
        ],
      },
    }),
  },
  required: false,
  defaultValue: [],
});
```

## Dynamic Data Properties

These properties provide more advanced options for collecting user input.

### Dropdown

This property allows for dynamically loaded options based on the user's input.

Board \*

Search a board…

Options load from the connected account.

```typescript theme={null}
Property.Dropdown({
  displayName: 'Options',
  description: 'Select an option',
  required: true,
  auth: yourPieceAuth,
  refreshers: ['auth'],
  refreshOnSearch: false,
  options: async ({ auth }, { searchValue }) => {
    // Search value only works when refreshOnSearch is true
    if (!auth) {
      return {
        disabled: true,
      };
    }
    return {
      options: [
        {
          label: 'Option One',
          value: '1',
        },
        {
          label: 'Option Two',
          value: '2',
        },
      ],
    };
  },
});
```

> [!TIP]
>
> When accessing the Piece auth, be sure to use exactly `auth` as it is
> hardcoded. However, for other properties, use their respective names.

### Multi-Select Dropdown

This property allows for multiple selections from dynamically loaded options.

Labels \*

Work ×
Important ×

```typescript theme={null}
Property.MultiSelectDropdown({
  displayName: 'Options',
  description: 'Select one or more options',
  required: true,
  refreshers: ['auth'],
  auth: yourPieceAuth,
  options: async ({ auth }) => {
    if (!auth) {
      return {
        disabled: true,
      };
    }
    return {
      options: [
        {
          label: 'Option One',
          value: '1',
        },
        {
          label: 'Option Two',
          value: '2',
        },
      ],
    };
  },
});
```

> [!TIP]
>
> When accessing the Piece auth, be sure to use exactly `auth` as it is
> hardcoded. However, for other properties, use their respective names.

### Dynamic Properties

This property is used to construct forms dynamically based on API responses or user input.

Property 1 \*

Enter property 1

Property 2

0

Fields are built at runtime from the API response.

```typescript theme={null}

import {
	httpClient,
	HttpMethod,
} from '@activepieces/pieces-common';


Property.DynamicProperties({
  description: 'Dynamic Form',
  displayName: 'Dynamic Form',
  required: true,
  refreshers: ['auth'],
  auth: yourPieceAuth,
  props: async ({auth}) => {
    const apiEndpoint = 'https://someapi.com';
    const response = await httpClient.sendRequest<{ values: [string[]][] }>({
        method: HttpMethod.GET,
        url: apiEndpoint ,
        //you can add the auth value to the headers
	  });

    const properties = {
      prop1: Property.ShortText({
        displayName: 'Property 1',
        description: 'Enter property 1',
        required: true,
      }),
      prop2: Property.Number({
        displayName: 'Property 2',
        description: 'Enter property 2',
        required: false,
      }),
    };

    return properties;
  },
});
```

## Layout & display options

Every property accepts a few optional hints that fine-tune how it renders. They are ignored where they don't apply, so they're always safe to add.

| Hint | Applies to | Effect |
| - | - | - |
| `placeholder` | text inputs | Grey hint text shown inside an empty field (e.g. `you@example.com`). |
| `width: 'half'` | any prop inside a group | Renders two fields side-by-side instead of full-width. |
| `icon` | any prop, `section` and `builder` groups | A named icon shown beside the field in the filter builder, or in the header of a section card. One of `text`, `code`, `markdown`, `reply`, `reply-all`, `users`, `user`, `send`, `type`, `file`, `paperclip`, `location`, `tag`, `inbox`, `calendar`, `trash`, `filter`, `sliders`, `blank`; any other name renders nothing. |
| `advanced: true` | any prop | Moves the field into the collapsible *Advanced* section. Props render in the main form by default. |

Every property renders in the main form by default, required or not. Set `advanced: true` on a secondary option to tuck it into the collapsible **Advanced** section; `advanced: false` is the default and has no effect. Avoid the flag on required props: the section starts collapsed, so a mandatory field hidden there only surfaces as a validation error.

**Half-width fields**

First name

Jane

Last name

Doe

```typescript theme={null}
props: {
  first_name: Property.ShortText({ displayName: 'First name', required: false, width: 'half' }),
  last_name: Property.ShortText({ displayName: 'Last name', required: false, width: 'half' }),
}
```

## Grouping properties

Actions and triggers can declare `propertyGroups` to organize related fields. Each group references its members by name and chooses how they render with `display`.

### Segmented tabs

`display: 'tabs'` groups a set of props into a segmented tab control, for example To / Cc / Bcc recipients.

Recipients \*

Type an email and press Enter

```typescript theme={null}
createAction({
  // ...
  propertyGroups: [
    {
      key: 'recipients',
      display: 'tabs',
      label: 'Recipients',
      description: 'Who receives this email. Use Cc and Bcc for additional recipients.',
      props: ['to', 'cc', 'bcc'],
    },
  ],
  props: {
    to: Property.Array({ displayName: 'To', required: true }),
    cc: Property.Array({ displayName: 'Cc', required: false }),
    bcc: Property.Array({ displayName: 'Bcc', required: false }),
  },
});
```

### Filter builder

For search / list actions, `display: 'builder'` renders a progressive **"Add filter"** builder: the user starts with an empty step and adds only the filters they need from a searchable, categorized picker. Each `builder` group becomes a picker category; a `footer` group pins a control (such as a result limit) below the list.

From

[sender@example.com](mailto:sender@example.com)

×

Date

Last 7 days

×

* Add filter

Returns up to 10 results

2 filters applied · newest first

−10+

```typescript theme={null}
createAction({
  // ...
  propertyGroups: [
    { key: 'people',  display: 'builder', label: 'People',  icon: 'users',    props: ['from', 'to'] },
    { key: 'time',    display: 'builder', label: 'Time',    icon: 'calendar', props: ['date_range'] },
    { key: 'footer',  display: 'footer',  props: ['max_results'] },
  ],
  props: {
    from: Property.ShortText({ displayName: 'From', required: false, icon: 'user', placeholder: 'sender@example.com' }),
    to: Property.ShortText({ displayName: 'To', required: false, icon: 'send', placeholder: 'recipient@example.com' }),
    date_range: Property.DateRange({ displayName: 'Date', required: false, display: 'dropdown', icon: 'calendar' }),
    max_results: Property.Number({ displayName: 'Max results', required: false, defaultValue: 10, display: 'stepper', min: 1, max: 500 }),
  },
});
```

> [!TIP]
>
> A filter row is shown when its value is set, so there's nothing extra to persist. Give filters short `placeholder` hints and an `icon` so each row reads clearly. Note that a `builder` or `footer` group also switches off the *Advanced* section for the whole step: every prop lives in the builder.

### Sectioned cards

`display: 'section'` groups related props into titled cards, for example a *Send to* card and a *Message* card. Unlike tabs and the filter builder, sectioned layouts **keep the collapsible *Advanced* section** for props outside the cards: an ungrouped prop still honours `advanced: true`, unless it is a checkbox `reveals` target, which renders inline under its toggle instead. Props inside a section are always essential. Give each group a `label` and `icon`, and use `width: 'half'` on members to pack two fields per row.

Send to

Chat Id \*

@channelusername or 123456789

Message

Format

Message \*

The message to be sent

Advanced
5 options ›

```typescript theme={null}
createAction({
  // ...
  propertyGroups: [
    { key: 'destination', display: 'section', label: 'Send to', icon: 'send', props: ['chat_id'] },
    { key: 'message',     display: 'section', label: 'Message',  icon: 'text', props: ['format', 'message'] },
  ],
  props: {
    chat_id: Property.ShortText({ displayName: 'Chat Id', required: true, placeholder: '@channelusername or 123456789' }),
    format: Property.StaticDropdown({ displayName: 'Format', required: false, display: 'cards', options: { options: [/* Markdown / HTML / Plain */] } }),
    message: Property.RichText({ displayName: 'Message', required: true, formatProperty: 'format' }),
    // ungrouped props can opt into Advanced with advanced: true
    disable_notification: Property.Checkbox({ displayName: 'Disable notification', required: false, advanced: true }),
  },
});
```

### Custom Property (BETA)

> [!WARNING]
>
> This feature is still in BETA and not fully released yet, please let us know if you use it and face any issues and consider it a possibility could have breaking changes in the future

Custom Property \*

Rendered by your own JS / DOM

This is a property that lets you inject JS code into the frontend and manipulate the DOM of this content however you like, it is extremely useful in case you are [embedding](https://www.activepieces.com/docs/embedding/overview.md) Activepieces and want to have a way to communicate with the SaaS embedding it.
It has a `code` property which is a function that takes in an object parameter which will have the following schema:

| Parameter Name | Type | Description |
| - | - | - |
| onChange | `(value:unknown)=>void` | A callback you call to set the value of your input (only call this inside event handlers) |
| value | `unknown` | Whatever the type of the value you pass to onChange |
| containerId | `string` | The ID of an HTML element in which you can modify the DOM however you like |
| isEmbedded | `boolean` | The flag that tells you if the code is running inside an [embedded instance](https://www.activepieces.com/docs/embedding/overview.md) of Activepieces |
| projectId | `string` | The project ID of the flow the step that contains this property is in |
| disabled | `boolean` | The flag that tells you whether or not the property is disabled |
| property | `{ displayName:string, description?: string, required: boolean}` | The current property information |

* You can return a clean up function at the end of the `code` property function to remove any listeners or HTML elements you inserted (this is important for development mode, the component gets [mounted twice](https://react.dev/reference/react/useEffect#my-effect-runs-twice-when-the-component-mounts)).
* This function must be pure without any imports from external packages or variables outside the function scope.
* **Must** mark your piece `minimumSupportedRelease` property to be at least `0.58.0` after introducing this property to it.

Here is how to define such a property:

```typescript theme={null}
 Property.Custom({
      code:(({value,onChange,containerId})=>{
        const container = document.getElementById(containerId);
        const input = document.createElement('input');
        input.classList.add(...['border','border-solid', 'border-border', 'rounded-md']) 
        input.type = 'text';
        input.value = `${value}`;
        input.oninput = (e: Event) => {
          const value = (e.target as HTMLInputElement).value;
          onChange(value);
        }
       container!.appendChild(input);
       const windowCallback = (e:MessageEvent<{type:string,value:string,propertyName:string}>) => {
        if(e.data.type === 'updateInput' && e.data.propertyName === 'YOUR_PROPERTY_NAME'){
          input.value= e.data.value;
          onChange(e.data.value);
        }
       }
       window.addEventListener('message', windowCallback);
        return ()=>{
          window.removeEventListener('message', windowCallback);
          container!.removeChild(input);
        }
      }),
      displayName: 'Custom Property',
      required: true
    })
```

* If you would like to know more about how to setup communication between Activepieces and the SaaS that's embedding it, check the [window postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.